huaweicloud-devkit 0.1.21 → 0.1.23

package/plugins/huaweicloud-core/skills/huawei-dew/SKILL.md

@@ -1,97 +1,97 @@
----
-name: huawei-dew
-description: "Use when managing secrets, credentials, encryption keys, certificates, or any sensitive data on Huawei Cloud. Covers CSMS (Cloud Secret Management Service) for secrets, KMS for encryption keys, and credential rotation. Triggers on: secret, credential, API key, token, password, encrypt, decrypt, KMS, CSMS, DEW, certificate, CSR, rotation. Activates for ANY task involving secrets or credentials — load this skill first before touching secrets."
-version: 1
----
-
-# Huawei Cloud DEW (Data Encryption Workshop)
-
-**STOP - Do not answer from general knowledge.** Follow the procedure below.
-
-Always run `hcloud <Service> <Operation> --help` before constructing commands to discover exact parameter names and requirements.
-
-## Overview
-
-Domain expertise for Huawei Cloud Data Encryption Workshop (DEW). Covers CSMS for secret lifecycle management, KMS for encryption key management, credential rotation, and secure application integration patterns.
-
-## Critical Warnings
-
-| Trap | Why |
-|------|-----|
-| NEVER fetch secret values into agent context | Use {{resolve:csms:secret-id:SecretString:key}} runtime injection |
-| NEVER echo credentials in conversation | AK/SK, passwords, tokens must never appear in chat |
-| KMS key deletion is irreversible | 7-30 day pending deletion window. Once gone, data is unrecoverable |
-| Secret rotation requires automation | Manual rotation risks stale credentials |
-| Cross-account KMS needs grants | KMS keys are regional. Cross-region data needs grant setup |
-
-## CSMS Operations
-
-### Read-only (safe — metadata only)
-| Operation | Description |
-|-----------|-------------|
-| ListSecrets | List all secrets (names only, no values) |
-| DescribeSecret | Get secret metadata (rotation config, KMS key, status) |
-| ListSecretVersions | List version IDs and stages (no values) |
-
-### Secret Value (blocked by policy — use runtime injection)
-| Operation | Safe Alternative |
-|-----------|-----------------|
-| DownloadSecret | Use {{resolve:csms:secret-id}} in IaC or SDK |
-| ShowSecretVersion | Use runtime injection, never in agent context |
-| GetSecretValue | Blocked. Use MCP proxy resolve pattern |
-
-## KMS Operations
-
-| Task | Command | Notes |
-|------|---------|-------|
-| List keys | hcloud KMS ListKeys | Read-only |
-| Create key | hcloud KMS CreateKey --key_alias=<name> | Requires write approval |
-| Encrypt | hcloud KMS EncryptData --key_id=<id> --plaintext=<b64> | Prefer SDK offline encrypt |
-| Decrypt | hcloud KMS DecryptData (**BLOCKED**) | Use runtime injection |
-
-## Runtime Injection Pattern
-
-`ash
-# Terraform / IaC
-resource "huaweicloud_csms_secret" "db_password" {
-  secret_string = var.db_password  # NEVER hardcode
-}
-
-# SDK
-secret_value = client.get_secret(secret_id="my-secret")
-# Use immediately, never print or store in context
-
-# hcloud (for approved automation only)
-hcloud CSMS DownloadSecret --secret_name=<name>
-# WARNING: Output goes to stdout. Pipe directly, never capture in agent.
-`
-
-## Troubleshooting
-
-| Error | Root Cause -> Fix |
-|-------|------------------|
-| Secret not found | Wrong region or project -> Verify secret ARN includes region/project |
-| AccessDenied on CSMS | Missing IAM CSMS policy -> Add csms:DescribeSecret + kms:Decrypt |
-| KMS key disabled | Key scheduled for deletion or manually disabled -> Enable or create new key |
-| Rotation stuck | Lambda/Python function error -> Check rotation function logs |
-
-## Security Considerations
-
-- MUST use runtime injection. NEVER fetch secrets into agent context
-- MUST rotate credentials every 90 days
-- MUST enable automatic rotation for CSMS secrets
-- MUST audit KMS key usage via CTS
-- SHOULD use customer-managed keys (CMK) for sensitive data
-- MUST NOT use default KMS keys for production workloads
-
-## MCP Tools
-
-- huaweicloud_list_operations service=DEW or CSMS or KMS
-- huaweicloud_run_readonly_command for ListSecrets/ListKeys (metadata only)
-- huaweicloud_safety policy blocks all secret value reads
-
-## References
-
-- DEW Docs: https://support.huaweicloud.com/dew/
-- CSMS usage: references/csms-usage.md
-- KMS usage: references/kms-usage.md
+---
+name: huawei-dew
+description: "Use when managing secrets, credentials, encryption keys, certificates, or any sensitive data on Huawei Cloud. Covers CSMS (Cloud Secret Management Service) for secrets, KMS for encryption keys, and credential rotation. Triggers on: secret, credential, API key, token, password, encrypt, decrypt, KMS, CSMS, DEW, certificate, CSR, rotation. Activates for ANY task involving secrets or credentials — load this skill first before touching secrets."
+version: 1
+---
+
+# Huawei Cloud DEW (Data Encryption Workshop)
+
+**STOP - Do not answer from general knowledge.** Follow the procedure below.
+
+Always run `hcloud <Service> <Operation> --help` before constructing commands to discover exact parameter names and requirements.
+
+## Overview
+
+Domain expertise for Huawei Cloud Data Encryption Workshop (DEW). Covers CSMS for secret lifecycle management, KMS for encryption key management, credential rotation, and secure application integration patterns.
+
+## Critical Warnings
+
+| Trap | Why |
+|------|-----|
+| NEVER fetch secret values into agent context | Use {{resolve:csms:secret-id:SecretString:key}} runtime injection |
+| NEVER echo credentials in conversation | AK/SK, passwords, tokens must never appear in chat |
+| KMS key deletion is irreversible | 7-30 day pending deletion window. Once gone, data is unrecoverable |
+| Secret rotation requires automation | Manual rotation risks stale credentials |
+| Cross-account KMS needs grants | KMS keys are regional. Cross-region data needs grant setup |
+
+## CSMS Operations
+
+### Read-only (safe — metadata only)
+| Operation | Description |
+|-----------|-------------|
+| ListSecrets | List all secrets (names only, no values) |
+| DescribeSecret | Get secret metadata (rotation config, KMS key, status) |
+| ListSecretVersions | List version IDs and stages (no values) |
+
+### Secret Value (blocked by policy — use runtime injection)
+| Operation | Safe Alternative |
+|-----------|-----------------|
+| DownloadSecret | Use {{resolve:csms:secret-id}} in IaC or SDK |
+| ShowSecretVersion | Use runtime injection, never in agent context |
+| GetSecretValue | Blocked. Use MCP proxy resolve pattern |
+
+## KMS Operations
+
+| Task | Command | Notes |
+|------|---------|-------|
+| List keys | hcloud KMS ListKeys | Read-only |
+| Create key | hcloud KMS CreateKey --key_alias=<name> | Requires write approval |
+| Encrypt | hcloud KMS EncryptData --key_id=<id> --plaintext=<b64> | Prefer SDK offline encrypt |
+| Decrypt | hcloud KMS DecryptData (**BLOCKED**) | Use runtime injection |
+
+## Runtime Injection Pattern
+
+`ash
+# Terraform / IaC
+resource "huaweicloud_csms_secret" "db_password" {
+  secret_string = var.db_password  # NEVER hardcode
+}
+
+# SDK
+secret_value = client.get_secret(secret_id="my-secret")
+# Use immediately, never print or store in context
+
+# hcloud (for approved automation only)
+hcloud CSMS DownloadSecret --secret_name=<name>
+# WARNING: Output goes to stdout. Pipe directly, never capture in agent.
+`
+
+## Troubleshooting
+
+| Error | Root Cause -> Fix |
+|-------|------------------|
+| Secret not found | Wrong region or project -> Verify secret ARN includes region/project |
+| AccessDenied on CSMS | Missing IAM CSMS policy -> Add csms:DescribeSecret + kms:Decrypt |
+| KMS key disabled | Key scheduled for deletion or manually disabled -> Enable or create new key |
+| Rotation stuck | Lambda/Python function error -> Check rotation function logs |
+
+## Security Considerations
+
+- MUST use runtime injection. NEVER fetch secrets into agent context
+- MUST rotate credentials every 90 days
+- MUST enable automatic rotation for CSMS secrets
+- MUST audit KMS key usage via CTS
+- SHOULD use customer-managed keys (CMK) for sensitive data
+- MUST NOT use default KMS keys for production workloads
+
+## MCP Tools
+
+- huaweicloud_list_operations service=DEW or CSMS or KMS
+- huaweicloud_run_readonly_command for ListSecrets/ListKeys (metadata only)
+- huaweicloud_safety policy blocks all secret value reads
+
+## References
+
+- DEW Docs: https://support.huaweicloud.com/dew/
+- CSMS usage: references/csms-usage.md
+- KMS usage: references/kms-usage.md

package/plugins/huaweicloud-core/skills/huawei-dew/references/csms-usage.md

@@ -1,29 +1,29 @@
-# CSMS Usage Guide
-
-## Create Secret
-hcloud CSMS CreateSecret --secret_name=prod-db-password --secret_string='{"password":"CHANGE_ME"}'
-
-## List Secrets (metadata only)
-hcloud CSMS ListSecrets
-
-## Describe Secret
-hcloud CSMS DescribeSecret --secret_name=prod-db-password
-
-## List Versions
-hcloud CSMS ListSecretVersions --secret_name=prod-db-password
-
-## Runtime Injection (Terraform)
-data "huaweicloud_csms_secret" "db" {
-  secret_name = "prod-db-password"
-}
-Use: data.huaweicloud_csms_secret.db.secret_string
-
-## Rotation
-- Enable auto-rotation: hcloud CSMS EnableSecretRotation --secret_name=<name> --rotation_interval=30
-- Rotation function ARN: provide Lambda to generate new secret value
-
-## Policy Rules
-- hcloud CSMS DownloadSecret -> BLOCKED (use runtime injection)
-- hcloud CSMS ShowSecretVersion -> BLOCKED
-- hcloud CSMS ListSecrets -> ALLOWED (metadata only)
-- hcloud CSMS DescribeSecret -> ALLOWED (metadata only)
+# CSMS Usage Guide
+
+## Create Secret
+hcloud CSMS CreateSecret --secret_name=prod-db-password --secret_string='{"password":"CHANGE_ME"}'
+
+## List Secrets (metadata only)
+hcloud CSMS ListSecrets
+
+## Describe Secret
+hcloud CSMS DescribeSecret --secret_name=prod-db-password
+
+## List Versions
+hcloud CSMS ListSecretVersions --secret_name=prod-db-password
+
+## Runtime Injection (Terraform)
+data "huaweicloud_csms_secret" "db" {
+  secret_name = "prod-db-password"
+}
+Use: data.huaweicloud_csms_secret.db.secret_string
+
+## Rotation
+- Enable auto-rotation: hcloud CSMS EnableSecretRotation --secret_name=<name> --rotation_interval=30
+- Rotation function ARN: provide Lambda to generate new secret value
+
+## Policy Rules
+- hcloud CSMS DownloadSecret -> BLOCKED (use runtime injection)
+- hcloud CSMS ShowSecretVersion -> BLOCKED
+- hcloud CSMS ListSecrets -> ALLOWED (metadata only)
+- hcloud CSMS DescribeSecret -> ALLOWED (metadata only)

package/plugins/huaweicloud-core/skills/huawei-dew/references/kms-usage.md

@@ -1,23 +1,23 @@
-# KMS Usage Guide
-
-## Create Key
-hcloud KMS CreateKey --key_alias=app-encryption-key --key_description="Application data encryption"
-
-## List Keys (metadata only)
-hcloud KMS ListKeys
-
-## Encrypt (offline preferred)
-hcloud KMS EncryptData --key_id=<key-id> --plaintext=<base64-data>
-
-## Decrypt (BLOCKED - use runtime)
-DO NOT use hcloud KMS DecryptData directly.
-Use SDK with KMS client in application runtime.
-
-## Key Rotation
-- Enable: hcloud KMS EnableKeyRotation --key_id=<key-id>
-- Rotation period: 365 days (default)
-
-## Key Deletion
-- Schedule: hcloud KMS ScheduleKeyDeletion --key_id=<key-id> --pending_days=7
-- Cancel during pending window: hcloud KMS CancelKeyDeletion --key_id=<key-id>
-- WARNING: After deletion window passes, data encrypted with this key is UNRECOVERABLE
+# KMS Usage Guide
+
+## Create Key
+hcloud KMS CreateKey --key_alias=app-encryption-key --key_description="Application data encryption"
+
+## List Keys (metadata only)
+hcloud KMS ListKeys
+
+## Encrypt (offline preferred)
+hcloud KMS EncryptData --key_id=<key-id> --plaintext=<base64-data>
+
+## Decrypt (BLOCKED - use runtime)
+DO NOT use hcloud KMS DecryptData directly.
+Use SDK with KMS client in application runtime.
+
+## Key Rotation
+- Enable: hcloud KMS EnableKeyRotation --key_id=<key-id>
+- Rotation period: 365 days (default)
+
+## Key Deletion
+- Schedule: hcloud KMS ScheduleKeyDeletion --key_id=<key-id> --pending_days=7
+- Cancel during pending window: hcloud KMS CancelKeyDeletion --key_id=<key-id>
+- WARNING: After deletion window passes, data encrypted with this key is UNRECOVERABLE

package/plugins/huaweicloud-core/skills/huawei-ecs/SKILL.md

@@ -1,131 +1,131 @@
----
-name: huawei-ecs
-description: "Use when creating, configuring, managing, or troubleshooting ECS instances on Huawei Cloud. Covers instance creation (hcloud ECS CreateServers), flavor selection, image management, security groups, EIP binding, disk attachment, auto-scaling (AS), and troubleshooting. Triggers on: ECS, instance, flavor, image, security group, EIP, EVS, auto-scaling. NOT for: CCE container workloads (use huawei-cce), BMS bare metal servers."
-version: 1
----
-
-# Huawei Cloud ECS
-
-**STOP - Do not answer from general knowledge.** Follow the procedure below.
-
-Always run `hcloud <Service> <Operation> --help` before constructing commands to discover exact parameter names and requirements.
-
-## Overview
-
-Domain expertise for Huawei Cloud Elastic Cloud Server (ECS). Covers instance lifecycle, flavor selection, image management, networking, storage attachment, auto-scaling, and troubleshooting.
-
-## Prerequisites
-
-Before creating an ECS instance from scratch, you MUST have:
-- A VPC (see `huawei-vpc`)
-- A subnet with DNS configured (see `huawei-vpc`)
-- A security group with application ports open (see `huawei-vpc`)
-
-If these do not exist, load the `huawei-vpc` skill first and create them before returning here.
-
-## Critical Warnings
-
-| Trap | Why |
-|------|-----|
-| Flavor not in region | Not all flavors available everywhere. Check with ECS ListFlavors first |
-| Security group denies all | New SGs deny ALL inbound. Must explicitly add rules |
-| EIP bills when idle | Unattached EIP still incurs charges |
-| Stopped instance still bills | Pay-per-use instances bill when stopped (unless shutdown-no-billing flavor) |
-| Disk survives instance delete | Deleting instance does NOT delete system disk by default |
-
-## Flavor Selection Guide
-
-Flavor families are **region-dependent**. Always run `hcloud ECS ListFlavors --cli-region=<r>` to discover available flavors before recommending.
-
-| Scenario | Family | What to look for |
-|----------|--------|-----------------|
-| Web app / microservices | General-purpose (ac, s, sn, c) | 2-4 vCPU, 4-8 GB RAM |
-| Database / big data | Memory-optimized (m, r) | 4-8 vCPU, 16-64 GB RAM |
-| AI inference | GPU (g, p) | 8+ vCPU, 64+ GB RAM + GPU |
-| HPC | High-IO (h, ir, i) | 8+ vCPU, local SSD |
-
-> See `references/flavors.md` for discovery workflow. **Do not hardcode flavor names** — availability changes by region and over time.
-
-## Common Workflows
-
-| Task | Command | Steps |
-|------|---------|-------|
-| List flavors | hcloud ECS ListFlavors --cli-region=<region> | references/flavors.md |
-| Create instance | hcloud ECS CreateServers --server.name=<n> --server.flavorRef=<id> --server.imageRef=<id> --server.nics.1.subnet_id=<id> --server.availability_zone=<az> | references/create-instance.md |
-| Find by name | See "How to search for instances" below | |
-| Bind EIP | hcloud EIP AssociatePublicips --publicip_id=<id> --publicip.associate_instance_id=<port-id> --publicip.associate_instance_type=PORT | Get port ID from `hcloud ECS ListServersDetails --server_id=<id>` → `OS-EXT-IPS:port_id` |
-| Security group rule | hcloud VPC CreateSecurityGroupRule --security_group_id=<id> --direction=<direction> --protocol=<protocol> | references/sg.md |
-| Attach disk | hcloud EVS AttachVolume --volume_id=<id> --server_id=<id> | references/evs.md |
-| Delete instance | hcloud ECS DeleteServers --servers.1.id=<id> --delete_publicip=true --delete_volume=true | references/create-instance.md |
-
-## How to Search for Instances
-
-`ListServersDetails` supports `--name` for exact match only. For fuzzy search:
-
-1. List all instances: `hcloud ECS ListServersDetails --cli-region=<region> --limit=100`
-2. Filter client-side by name substring, tag, or status
-3. Use `--server_tags` filter if instances are tagged: `hcloud ECS ListServersDetails --server_tags.1.key=Project`
-
-Abort if the result set is larger than `--limit` and ask the user to narrow the search.
-
-## Deleting Instances
-
-- Show the user the exact command and get explicit approval before running
-- By default, `--delete_publicip` and `--delete_volume` are **false** — public IP and system disk survive deletion
-- Set both to `true` to avoid orphaned resources and unexpected billing
-- Data disks ARE deleted by default (unlike system disk)
-
-## Troubleshooting
-
-| Error | Root Cause -> Fix |
-|-------|------------------|
-| Cannot SSH | SG missing port 22 or no EIP -> Add ingress rule / Bind EIP |
-| Flavor unavailable | Region limitation -> ListFlavors in target region |
-| Insufficient resources | Stock depleted -> Change flavor or AZ |
-| AuthFailure | Expired AK/SK -> hcloud configure init |
-| APIGW.0802 / region permission | IAM user has no access to this region -> IAM console → User → Permissions → add region, or switch to another region |
-
-## Security Considerations
-
-- MUST use security groups, not iptables
-- MUST store SSH keys in DEW, never in user-data
-- SHOULD enable CTS audit logging
-- MUST NOT open 0.0.0.0/0 for SSH
-
-## MCP Tools
-
-Prefer these tools over raw hcloud CLI — they enforce safety policies:
-
-- huaweicloud_list_operations service=ECS
-- huaweicloud_run_readonly_command for discovery (auto-redacts output)
-- huaweicloud_run_approved_command for writes (requires exact command approval)
-- huaweicloud_check_cli to verify hcloud is available
-
-## Without MCP (Fallback)
-
-If MCP tools are NOT available (new install, session not restarted):
-- Raw hcloud commands WILL appear in shell history — passwords and secrets are at risk
-- Always use key_name instead of adminPass
-- Verify safety manually: no secret value reads, no credential file access
-- Restart session as soon as possible to enable safety policies
-
-## Without MCP
-
-Fall back to hcloud CLI. State: "MCP unavailable, using local hcloud CLI."
-
-## Flexus (Lightweight ECS)
-
-Flexus is the lightweight ECS family. Two variants:
-
-| Variant | API | CLI | Billing |
-|---------|-----|:---:|---------|
-| **Flexus L** | HCSS (hcss:lightInstances) | ❌ No hcloud — Python SDK only | Prepaid only |
-| **Flexus X** | Standard ECS API | ✅ `hcloud ECS` with `x1.*` flavors | On-demand & prepaid |
-
-For Flexus X, use standard ECS CreateServers flow with `x1.*` flavors. For Flexus L, manual console provisioning is recommended — no KooCLI path exists.
-
-## References
-
-- ECS Docs: https://support.huaweicloud.com/ecs/
-- Flavor specs: references/flavors.md
-- Create instance: references/create-instance.md
+---
+name: huawei-ecs
+description: "Use when creating, configuring, managing, or troubleshooting ECS instances on Huawei Cloud. Covers instance creation (hcloud ECS CreateServers), flavor selection, image management, security groups, EIP binding, disk attachment, auto-scaling (AS), and troubleshooting. Triggers on: ECS, instance, flavor, image, security group, EIP, EVS, auto-scaling. NOT for: CCE container workloads (use huawei-cce), BMS bare metal servers."
+version: 1
+---
+
+# Huawei Cloud ECS
+
+**STOP - Do not answer from general knowledge.** Follow the procedure below.
+
+Always run `hcloud <Service> <Operation> --help` before constructing commands to discover exact parameter names and requirements.
+
+## Overview
+
+Domain expertise for Huawei Cloud Elastic Cloud Server (ECS). Covers instance lifecycle, flavor selection, image management, networking, storage attachment, auto-scaling, and troubleshooting.
+
+## Prerequisites
+
+Before creating an ECS instance from scratch, you MUST have:
+- A VPC (see `huawei-vpc`)
+- A subnet with DNS configured (see `huawei-vpc`)
+- A security group with application ports open (see `huawei-vpc`)
+
+If these do not exist, load the `huawei-vpc` skill first and create them before returning here.
+
+## Critical Warnings
+
+| Trap | Why |
+|------|-----|
+| Flavor not in region | Not all flavors available everywhere. Check with ECS ListFlavors first |
+| Security group denies all | New SGs deny ALL inbound. Must explicitly add rules |
+| EIP bills when idle | Unattached EIP still incurs charges |
+| Stopped instance still bills | Pay-per-use instances bill when stopped (unless shutdown-no-billing flavor) |
+| Disk survives instance delete | Deleting instance does NOT delete system disk by default |
+
+## Flavor Selection Guide
+
+Flavor families are **region-dependent**. Always run `hcloud ECS ListFlavors --cli-region=<r>` to discover available flavors before recommending.
+
+| Scenario | Family | What to look for |
+|----------|--------|-----------------|
+| Web app / microservices | General-purpose (ac, s, sn, c) | 2-4 vCPU, 4-8 GB RAM |
+| Database / big data | Memory-optimized (m, r) | 4-8 vCPU, 16-64 GB RAM |
+| AI inference | GPU (g, p) | 8+ vCPU, 64+ GB RAM + GPU |
+| HPC | High-IO (h, ir, i) | 8+ vCPU, local SSD |
+
+> See `references/flavors.md` for discovery workflow. **Do not hardcode flavor names** — availability changes by region and over time.
+
+## Common Workflows
+
+| Task | Command | Steps |
+|------|---------|-------|
+| List flavors | hcloud ECS ListFlavors --cli-region=<region> | references/flavors.md |
+| Create instance | hcloud ECS CreateServers --server.name=<n> --server.flavorRef=<id> --server.imageRef=<id> --server.nics.1.subnet_id=<id> --server.availability_zone=<az> | references/create-instance.md |
+| Find by name | See "How to search for instances" below | |
+| Bind EIP | hcloud EIP AssociatePublicips --publicip_id=<id> --publicip.associate_instance_id=<port-id> --publicip.associate_instance_type=PORT | Get port ID from `hcloud ECS ListServersDetails --server_id=<id>` → `OS-EXT-IPS:port_id` |
+| Security group rule | hcloud VPC CreateSecurityGroupRule --security_group_id=<id> --direction=<direction> --protocol=<protocol> | references/sg.md |
+| Attach disk | hcloud EVS AttachVolume --volume_id=<id> --server_id=<id> | references/evs.md |
+| Delete instance | hcloud ECS DeleteServers --servers.1.id=<id> --delete_publicip=true --delete_volume=true | references/create-instance.md |
+
+## How to Search for Instances
+
+`ListServersDetails` supports `--name` for exact match only. For fuzzy search:
+
+1. List all instances: `hcloud ECS ListServersDetails --cli-region=<region> --limit=100`
+2. Filter client-side by name substring, tag, or status
+3. Use `--server_tags` filter if instances are tagged: `hcloud ECS ListServersDetails --server_tags.1.key=Project`
+
+Abort if the result set is larger than `--limit` and ask the user to narrow the search.
+
+## Deleting Instances
+
+- Show the user the exact command and get explicit approval before running
+- By default, `--delete_publicip` and `--delete_volume` are **false** — public IP and system disk survive deletion
+- Set both to `true` to avoid orphaned resources and unexpected billing
+- Data disks ARE deleted by default (unlike system disk)
+
+## Troubleshooting
+
+| Error | Root Cause -> Fix |
+|-------|------------------|
+| Cannot SSH | SG missing port 22 or no EIP -> Add ingress rule / Bind EIP |
+| Flavor unavailable | Region limitation -> ListFlavors in target region |
+| Insufficient resources | Stock depleted -> Change flavor or AZ |
+| AuthFailure | Expired AK/SK -> hcloud configure init |
+| APIGW.0802 / region permission | IAM user has no access to this region -> IAM console → User → Permissions → add region, or switch to another region |
+
+## Security Considerations
+
+- MUST use security groups, not iptables
+- MUST store SSH keys in DEW, never in user-data
+- SHOULD enable CTS audit logging
+- MUST NOT open 0.0.0.0/0 for SSH
+
+## MCP Tools
+
+Prefer these tools over raw hcloud CLI — they enforce safety policies:
+
+- huaweicloud_list_operations service=ECS
+- huaweicloud_run_readonly_command for discovery (auto-redacts output)
+- huaweicloud_run_approved_command for writes (requires exact command approval)
+- huaweicloud_check_cli to verify hcloud is available
+
+## Without MCP (Fallback)
+
+If MCP tools are NOT available (new install, session not restarted):
+- Raw hcloud commands WILL appear in shell history — passwords and secrets are at risk
+- Always use key_name instead of adminPass
+- Verify safety manually: no secret value reads, no credential file access
+- Restart session as soon as possible to enable safety policies
+
+## Without MCP
+
+Fall back to hcloud CLI. State: "MCP unavailable, using local hcloud CLI."
+
+## Flexus (Lightweight ECS)
+
+Flexus is the lightweight ECS family. Two variants:
+
+| Variant | API | CLI | Billing |
+|---------|-----|:---:|---------|
+| **Flexus L** | HCSS (hcss:lightInstances) | ❌ No hcloud — Python SDK only | Prepaid only |
+| **Flexus X** | Standard ECS API | ✅ `hcloud ECS` with `x1.*` flavors | On-demand & prepaid |
+
+For Flexus X, use standard ECS CreateServers flow with `x1.*` flavors. For Flexus L, manual console provisioning is recommended — no KooCLI path exists.
+
+## References
+
+- ECS Docs: https://support.huaweicloud.com/ecs/
+- Flavor specs: references/flavors.md
+- Create instance: references/create-instance.md