huaweicloud-devkit 0.1.26-dev.0 → 1.0.1

package/plugins/huaweicloud-core/.cursor-plugin/plugin.json

@@ -1,44 +1,44 @@
 {
-    "interface":  {
-                      "displayName":  "HuaweiCloud Devkit",
-                      "shortDescription":  "HuaweiCloud Devkit - Huawei Cloud guidance, CLI/API/SDK routing, MCP tools, and safety for coding agents.",
-                      "longDescription":  "HuaweiCloud Devkit helps coding agents choose and use Huawei Cloud Skills, KooCLI, APIs, SDKs, and MCP tools with less context, safer command execution, and more accurate cloud implementation decisions.",
-                      "developerName":  "HuaweiCloud Mate",
-                      "category":  "Cloud",
-                      "capabilities":  [
-                                           "Read",
-                                           "Interactive"
-                                       ],
-                      "websiteURL":  "https://github.com/huaweicloud-mate/huaweicloud-devkit",
-                      "brandColor":  "#C7000B",
-                      "defaultPrompt":  [
-                                            "Help me choose the right Huawei Cloud capability.",
-                                            "Check my Huawei Cloud CLI setup safely.",
-                                            "Plan this Huawei Cloud API or SDK task."
-                                        ]
-                  },
-    "mcpServers":  "./.mcp.json",
-    "description":  "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
-    "skills":  "./skills/",
-    "version":  "0.1.23",
-    "author":  {
-                   "name":  "HuaweiCloud Mate",
-                   "url":  "https://github.com/huaweicloud-mate"
-               },
-    "hooks":  "./hooks/",
-    "name":  "huaweicloud-core",
-    "homepage":  "https://github.com/huaweicloud-mate/huaweicloud-devkit",
-    "repository":  "https://github.com/huaweicloud-mate/huaweicloud-devkit",
-    "license":  "Apache-2.0",
-    "keywords":  [
-                     "huaweicloud",
-                     "huawei-cloud",
-                     "koocli",
-                     "hcloud",
-                     "agent",
-                     "mcp",
-                     "api",
-                     "sdk",
-                     "skills"
-                 ]
-}
+  "interface": {
+    "displayName": "HuaweiCloud Devkit",
+    "shortDescription": "HuaweiCloud Devkit - Huawei Cloud guidance, CLI/API/SDK routing, MCP tools, and safety for coding agents.",
+    "longDescription": "HuaweiCloud Devkit helps coding agents choose and use Huawei Cloud Skills, KooCLI, APIs, SDKs, and MCP tools with less context, safer command execution, and more accurate cloud implementation decisions.",
+    "developerName": "HuaweiCloud Mate",
+    "category": "Cloud",
+    "capabilities": [
+      "Read",
+      "Interactive"
+    ],
+    "websiteURL": "https://github.com/huaweicloud/HuaweiCloud-Devkit",
+    "brandColor": "#C7000B",
+    "defaultPrompt": [
+      "Help me choose the right Huawei Cloud capability.",
+      "Check my Huawei Cloud CLI setup safely.",
+      "Plan this Huawei Cloud API or SDK task."
+    ]
+  },
+  "mcpServers": "./.mcp.json",
+  "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
+  "skills": "./skills/",
+  "version": "1.0.1",
+  "author": {
+    "name": "HuaweiCloud Mate",
+    "url": "https://github.com/huaweicloud"
+  },
+  "hooks": "./hooks/",
+  "name": "huaweicloud-core",
+  "homepage": "https://github.com/huaweicloud/HuaweiCloud-Devkit",
+  "repository": "https://github.com/huaweicloud/HuaweiCloud-Devkit",
+  "license": "Apache-2.0",
+  "keywords": [
+    "huaweicloud",
+    "huawei-cloud",
+    "koocli",
+    "hcloud",
+    "agent",
+    "mcp",
+    "api",
+    "sdk",
+    "skills"
+  ]
+}

package/plugins/huaweicloud-core/.mcp.json

@@ -5,8 +5,10 @@
       "args": [
         "./src/mcp-server.mjs"
       ],
+      "cwd": ".",
       "env": {
-        "HUAWEICLOUD_AGENT_TOOLKIT_MODE": "local"
+        "HUAWEICLOUD_AGENT_TOOLKIT_MODE": "local",
+        "HDKITSERVICE_ENDPOINT": ""
       }
     }
   }

package/plugins/huaweicloud-core/.workbuddy-plugin/plugin.json

@@ -0,0 +1,44 @@
+{
+  "name": "huaweicloud-core",
+  "version": "1.0.0",
+  "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
+  "author": {
+    "name": "HuaweiCloud Mate",
+    "url": "https://github.com/huaweicloud"
+  },
+  "homepage": "https://github.com/huaweicloud/HuaweiCloud-Devkit",
+  "repository": "https://github.com/huaweicloud/HuaweiCloud-Devkit",
+  "license": "Apache-2.0",
+  "keywords": [
+    "huaweicloud",
+    "huawei-cloud",
+    "koocli",
+    "hcloud",
+    "agent",
+    "mcp",
+    "api",
+    "sdk",
+    "skills"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "hooks": "./hooks/",
+  "interface": {
+    "displayName": "HuaweiCloud Devkit",
+    "shortDescription": "HuaweiCloud Devkit - Huawei Cloud guidance, CLI/API/SDK routing, MCP tools, and safety for coding agents.",
+    "longDescription": "HuaweiCloud Devkit helps coding agents choose and use Huawei Cloud Skills, KooCLI, APIs, SDKs, and MCP tools with less context, safer command execution, and more accurate cloud implementation decisions.",
+    "developerName": "HuaweiCloud Mate",
+    "category": "Cloud",
+    "capabilities": [
+      "Read",
+      "Interactive"
+    ],
+    "websiteURL": "https://github.com/huaweicloud/HuaweiCloud-Devkit",
+    "brandColor": "#C7000B",
+    "defaultPrompt": [
+      "Help me choose the right Huawei Cloud capability.",
+      "Check my Huawei Cloud CLI setup safely.",
+      "Plan this Huawei Cloud API or SDK task."
+    ]
+  }
+}

package/plugins/huaweicloud-core/safety/policy.json

@@ -82,5 +82,19 @@
                                  "ls",
                                  "dir",
                                  "Get-ChildItem"
-                             ]
+                             ],
+    "blockedSandboxCommands":  [
+                                  "rm\\s+-rf\\s+/",
+                                  "mkfs",
+                                  "dd\\s+if=",
+                                  ":\\(\\)\\{:\\|:&\\};:",
+                                  "shutdown",
+                                  "reboot",
+                                  "init\\s+[06]",
+                                  "fdisk"
+                              ],
+    "sandboxWriteTools":  [
+                               "huaweicloud_sandbox_connect",
+                               "huaweicloud_sandbox_credentials"
+                           ]
 }

package/plugins/huaweicloud-core/safety/rules/cloud-risk-rules.json

@@ -173,6 +173,27 @@
       },
       "message": "The generated plan may create high-cost or unbounded capacity.",
       "remediation": "Use small preview defaults, explicit quotas, budget labels, and user approval before creating high-cost resources."
+    },
+    {
+      "id": "hwc-sandbox-destructive-command",
+      "title": "Destructive command in sandbox terminal",
+      "category": "destructive",
+      "severity": "deny",
+      "stages": ["command"],
+      "match": {
+        "any": [
+          { "field": "text", "regex": "rm\\s+-rf\\s+/" },
+          { "field": "text", "regex": "mkfs" },
+          { "field": "text", "regex": "dd\\s+if=" },
+          { "field": "text", "regex": ":\\\\(\\\\)\\\\{[^}]*\\\\|[^}]*&[^}]*\\\\}[^;]*;:" },
+          { "field": "text", "regex": "\\bshutdown\\b" },
+          { "field": "text", "regex": "\\breboot\\b" },
+          { "field": "text", "regex": "\\binit\\s+[06]\\b" },
+          { "field": "text", "regex": "\\bfdisk\\b" }
+        ]
+      },
+      "message": "The sandbox terminal command is destructively dangerous and could destroy the workspace.",
+      "remediation": "Use targeted deletions instead of recursive root removal. Avoid disk format, fork bombs, and system shutdown commands in sandbox terminals."
     }
   ]
 }

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

@@ -54,14 +54,34 @@ Key gotchas when creating:
 
 ### Add Public Access (ELB Provider Only)
 
+`BASIC` instances have no public IP. Use `PROFESSIONAL` + `elb` provider for public access (`lvs` is internal-only).
+
 ```bash
 hcloud APIG AddIngressEipV2 \
   --instance_id=<id> \
   --bandwidth_charging_mode=bandwidth \
-  --bandwidth_size=5
+  --bandwidth_size=<size>
+```
+
+To use an existing EIP instead of creating a new one:
+
+```bash
+hcloud APIG AddIngressEipV2 \
+  --instance_id=<id> \
+  --eip_id=<existing-eip-id>
 ```
 
-> `AddIngressEipV2` only works with `elb` provider. `AddEipV2` requires `lvs` provider. Bandwidth minimum is 5 Mbps.
+> `AddIngressEipV2` only works with `elb` provider. `AddEipV2` (without "Ingress") requires `lvs` provider. Bandwidth minimum is 5 Mbps.
+
+**Verification** — After binding, poll the instance to confirm EIP is active:
+
+```bash
+hcloud APIG ListInstancesV2 --cli-region=<region> --instance_id=<id> --cli-output=json | jq '.instances[0].eip_address'
+```
+
+Wait for `eip_address` to show a valid IP (may take up to 2 minutes). If `eip_address` is still `null` after 2 minutes, the EIP may not have been assigned.
+
+> **Trap**: `sl_domain` from `CreateApiGroupV2` is an **internal-only** domain (e.g., `*.apic.cn-north-4.huaweicloudapis.com`). It may resolve to internal IP only (NXDOMAIN from public internet). **For public access, always use the `eip_address` from the instance**, not the `sl_domain` or trigger `invoke_url`.
 
 ## API Group
 

package/plugins/huaweicloud-core/skills/huawei-cloud-eye/SKILL.md

@@ -53,6 +53,23 @@ hcloud CES CreateAlarm --help
 # --condition.comparison_operator, --condition.count
 ```
 
+### `--condition.comparison_operator` Legal Values
+
+For metric alarms use **symbols** (NOT words like `gt`/`lt`):
+
+| Value | Meaning |
+|-------|---------|
+| `>` | Greater than |
+| `>=` | Greater than or equal |
+| `<` | Less than |
+| `<=` | Less than or equal |
+| `=` | Equal |
+| `!=` | Not equal |
+
+For event alarms: `cycle_decrease`, `cycle_increase`, `cycle_wave`.
+
+> **Trap**: Shell may interpret `>` and `<` as redirect operators. Always quote: `--condition.comparison_operator=">="` or use `--cli-jsonInput=<file>`.
+
 ## Troubleshooting
 
 | Error | Fix |

package/plugins/huaweicloud-core/skills/huawei-cloud-find-skills/SKILL.md

@@ -12,7 +12,7 @@ description: |
 
 # Huawei Cloud Agent Skills Search and Discovery
 
-This skill enables users to efficiently search, discover, and install Huawei Cloud skills. 
+This skill enables users to efficiently search, discover, and install Huawei Cloud skills.
 
 ## Scenario Description
 

package/plugins/huaweicloud-core/skills/huawei-dds-dcs/SKILL.md

@@ -12,7 +12,7 @@ Always run `hcloud DDS <Operation> --help` or `hcloud DCS <Operation> --help` be
 
 ## DDS (Document Database Service — MongoDB Compatible)
 
-## Critical Warnings
+## DDS Critical Warnings
 
 | Trap | Why |
 |------|-----|
@@ -35,7 +35,7 @@ Discover exact parameters with `--help` before executing any command.
 
 ## DCS (Distributed Cache Service — Redis/Memcached)
 
-## Critical Warnings
+## DCS Critical Warnings
 
 | Trap | Why |
 |------|-----|

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

@@ -57,6 +57,7 @@ Flavor families are **region-dependent**. Always run `hcloud ECS ListFlavors --c
 | 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 |
+| Reboot instance | hcloud ECS BatchRebootServers --reboot.servers.1.id=<id> --reboot.type=SOFT | NOT `RebootServer` — that operation does not exist |
 
 ## How to Search for Instances
 
@@ -66,8 +67,57 @@ Flavor families are **region-dependent**. Always run `hcloud ECS ListFlavors --c
 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`
 
+> **Return structure**: `ListServersDetails` returns `{"servers": [...]}` (array), NOT `{"server": ...}`. Parse as `.servers[0].status`, NOT `.server.status`.
+
 Abort if the result set is larger than `--limit` and ask the user to narrow the search.
 
+## Instance Status Polling
+
+ECS creation is asynchronous. Status transitions: `BUILD` → `ACTIVE` (or `ERROR`). Wait times vary widely (20s–3min), never use fixed sleep.
+
+Poll strategy:
+
+```bash
+for i in $(seq 1 30); do
+  status=$(hcloud ECS ListServersDetails --cli-region=<region> --server_id=<id> --cli-output=json | jq -r '.servers[0].status')
+  if [ "$status" = "ACTIVE" ]; then break; fi
+  if [ "$status" = "ERROR" ]; then echo "Creation failed"; exit 1; fi
+  sleep 10
+done
+```
+
+- Poll interval: 10 seconds
+- Maximum wait: 5 minutes (30 iterations)
+- Check for `ERROR` status to detect creation failures early
+
+## SSH Connection Verification
+
+After ECS is ACTIVE and EIP is bound, verify SSH connectivity:
+
+```bash
+hcloud ECS ListServersDetails --cli-region=<region> --server_id=<id>
+# → addresses.<vpc-id>[].OS-EXT-IPS:addr
+
+ssh -o StrictHostKeyChecking=accept-new -i <path-to-private-key> root@<eip-address>
+```
+
+> **SSH verification checklist**: EIP bound → security group has port 22 ingress → keypair private key saved locally → known_hosts handled with `StrictHostKeyChecking=accept-new` (or delete stale entries with `ssh-keygen -R <ip>`).
+
+### Running Commands Inside the Instance
+
+Use SSH for any in-instance operations (install software, check logs, start services):
+
+```bash
+ssh -o StrictHostKeyChecking=accept-new -i <key> root@<eip> 'command'
+```
+
+Example — re-run failed cloud-init setup manually:
+```bash
+ssh -o StrictHostKeyChecking=accept-new -i <key> root@<eip> 'dnf install -y nginx && systemctl enable --now nginx'
+```
+
+> If SCP blocks SSH, use cloud-init `--server.user_data` for full deployment instead. See `references/create-instance.md` §Bootstrap.
+
 ## Deleting Instances
 
 - Show the user the exact command and get explicit approval before running
@@ -82,7 +132,7 @@ Abort if the result set is larger than `--limit` and ask the user to narrow the
 | 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 |
+| AuthFailure | Expired AK/SK -> re-run `npx huaweicloud-devkit auth init` |
 | APIGW.0802 / region permission | IAM user has no access to this region -> IAM console → User → Permissions → add region, or switch to another region |
 | Cannot SSH (port 22 open) | SCP policy may be blocking SSH. Check `SYS.0403` errors in command output -> Use cloud-init/user_data for initial setup instead. See `references/create-instance.md` §Bootstrap |
 

package/plugins/huaweicloud-core/skills/huawei-ecs/references/create-instance.md

@@ -59,8 +59,13 @@ hcloud ECS CreateServers ... --server.user_data=$user_data
 ```
 
 > **Security**: Never embed secrets (passwords, AK/SK, tokens) in user_data. It is stored unencrypted and readable from within the instance via IMDS. Fetch secrets at boot from DEW/CSMS instead.
-
+>
 > **Debugging**: If the script didn't run, check `/var/log/cloud-init-output.log` on the instance.
+>
+> **Recovery after failure**: user_data only executes on **first boot**. Restarting the instance will NOT re-run user_data scripts. If cloud-init fails (e.g., DNS missing → `yum`/`apt` cannot resolve repos):
+> 1. Fix the root cause (e.g., update subnet DNS via `VPC UpdateSubnet`)
+> 2. Either: SSH into the instance and run the setup commands manually (see `huawei-ecs` → SSH Connection Verification → Running Commands Inside the Instance)
+> 3. Or: Delete the instance and recreate with corrected user_data (fresh boot)
 
 ## 7. EIP (two methods)
 
@@ -81,16 +86,31 @@ hcloud ECS CreateServers \
 ### Method B: Create and bind separately
 hcloud EIP CreatePublicip --publicip.type=<type> --bandwidth.size=<size> --bandwidth.share_type=<share-type> --bandwidth.name=<name>
 
+```bash
 # Get the ECS network port ID
 hcloud ECS ListServersDetails --cli-region=<region> --server_id=<instance-id>
 # → addresses.<vpc-id>[].OS-EXT-IPS:port_id
 
 # Bind EIP via port
 hcloud EIP AssociatePublicips --publicip_id=<eip-id> --publicip.associate_instance_id=<port-id> --publicip.associate_instance_type=PORT
+```
 
 ## 8. Verify
-hcloud ECS ListServersDetails --cli-region=<region> --server_id=<instance-id>
-Expected: status=ACTIVE
+
+ECS creation is asynchronous. Wait times vary widely (20s to 3min). Status transitions: `BUILD` → `ACTIVE` (or `ERROR`). Never use fixed sleep — poll actively:
+
+```bash
+for i in $(seq 1 30); do
+  status=$(hcloud ECS ListServersDetails --cli-region=<region> --server_id=<instance-id> --cli-output=json | jq -r '.servers[0].status')
+  if [ "$status" = "ACTIVE" ]; then break; fi
+  if [ "$status" = "ERROR" ]; then echo "Creation failed"; exit 1; fi
+  sleep 10
+done
+```
+
+- Poll interval: 10 seconds
+- Maximum wait: 5 minutes (30 iterations)
+- After ACTIVE, confirm once more: `hcloud ECS ListServersDetails --cli-region=<region> --server_id=<instance-id>`
 
 ### Verify HTTP accessibility (if EIP bound)
 

package/plugins/huaweicloud-core/skills/huawei-ecs/references/troubleshooting.md

@@ -13,7 +13,7 @@
 | Cannot SSH | 安全组未开放22端口 或 未绑定EIP | 1) 添加入方向规则 tcp 22。2) `hcloud EIP BindPublicIp` |
 | Flavor unavailable | 区域不支持该规格 | `hcloud ECS ListFlavors --cli-region=<r>` 先查。不硬编码 s6/m6 等规格名 |
 | Insufficient resources | AZ 库存不足 | 换规格、换 AZ、或等待资源释放 |
-| AuthFailure | AK/SK 过期或无效 | `hcloud configure init` 重新配置 |
+| AuthFailure | AK/SK 过期或无效 | `npx huaweicloud-devkit auth init` 重新配置统一凭据 |
 
 ## 创建失败诊断流程
 

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

@@ -95,7 +95,7 @@ See `references/deploy-workflow.md` for a step-by-step example with code templat
 | DeleteFunction with `:latest` | Strip `:latest` version suffix from URN |
 | Code too large | Inline limit 10KB — use `zip`/`obs` code type |
 | Cold start slow | Set reserved instances for critical functions |
-| Auth failure | Run `hcloud configure init` |
+| Auth failure | Run `npx huaweicloud-devkit auth init` |
 
 ## Security Considerations
 

package/plugins/huaweicloud-core/skills/huawei-functiongraph/references/triggers.md

@@ -138,5 +138,5 @@ hcloud FunctionGraph DeleteFunctionTrigger --function_urn=<urn> --trigger_type_c
 ```
 
 > Deleting a trigger does NOT cascade-delete the associated APIG API. After `DeleteFunctionTrigger`, also run `hcloud APIG ListApisV2 --instance_id=<id>` and delete orphaned APIs to avoid resource residue.
-
+>
 > **APIG event format**: When using DEDICATEDGATEWAY, the event body is Base64 encoded and uses a non-standard structure. See `apig-event-format.md` for handler templates.

package/plugins/huaweicloud-core/skills/huawei-getting-started/SKILL.md

@@ -19,11 +19,11 @@ version: 1
 ## First-Time Setup
 1. **Install KooCLI** using command above
 2. **Accept privacy policy** (first run only): KooCLI requires one-time privacy agreement. Run `hcloud version` to read the agreement, then respond `y` to accept. Do not pipe `echo "y" |` — you must review the terms first.
-3. **Configure credentials**: `hcloud configure init` (interactive, prompts for AK/SK/region safely)
+3. **Configure credentials (unified)**: `npx huaweicloud-devkit auth init` — prefer this over `hcloud configure init`, which only covers KooCLI.
 4. **Verify**: `hcloud configure list` to confirm profile, then `hcloud ECS ListServersDetails --cli-region=cn-north-4`
 5. For detailed auth guidance, see `huaweicloud-cli-and-auth` skill
 
-> **Security**: Never pass AK/SK as command-line arguments (`--ak=...`). Always use `hcloud configure init` (interactive) or `hcloud configure set` with cached profile to avoid secrets in shell history.
+> **Security**: Never pass AK/SK as command-line arguments (`--ak=...`). Always use `npx huaweicloud-devkit auth init` (unified, interactive, recommended) or `hcloud configure init` (KooCLI only) to avoid secrets in shell history.
 
 ### Non-Interactive Setup (Agent/CI Environments)
 

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

@@ -31,7 +31,7 @@ Domain expertise for Huawei Cloud Object Storage Service (OBS). Covers bucket/ob
 
 | Trap | Why |
 |------|-----|
-| Bucket name is global | All users share bucket namespace |
+| Bucket name is global | All users share bucket namespace. Always use a unique name: `{prefix}-{timestamp}` (e.g. `mybucket-20260810155048`) |
 | Three-layer permissions | IAM > Bucket Policy > ACL. Most restrictive wins |
 | Versioning is irreversible | Once enabled, cannot be disabled, only suspended |
 | OBS uses AK/SK directly | NOT IAM tokens. Auth errors mean check AK/SK validity |
@@ -42,7 +42,17 @@ Domain expertise for Huawei Cloud Object Storage Service (OBS). Covers bucket/ob
 
 ## OBS Credential Setup (Required Before First Use)
 
-KooCLI OBS uses a separate config file (`~/.obsutilconfig`), NOT `~/.hcloud/config.json`. Call `huaweicloud_setup_obs_config` to automatically sync credentials from the active hcloud profile. No manual AK/SK entry needed.
+KooCLI OBS uses a separate config file (`~/.obsutilconfig`), NOT `~/.hcloud/config.json`. All OBS commands fail with credential errors until this is configured.
+
+**In-session bootstrap (recommended)**: Call `huaweicloud_setup_obs_config` — it syncs AK/SK from the active hcloud profile automatically. No manual key entry needed. Run this once per session before any OBS command.
+
+**CLI fallback** (if MCP tools unavailable):
+
+```bash
+hcloud OBS config -e=<endpoint> -i=<AK> -k=<SK> -t=token
+```
+
+> `huaweicloud_setup_obs_config` should be called at the start of every OBS task — never assume credentials are pre-configured from a previous session.
 
 ## Common Workflows
 
@@ -69,6 +79,13 @@ Build → Create bucket → Upload → Set bucket ACL → Set object ACL → Con
 
 > KooCLI OBS does NOT support `SetBucketWebsite`. Configure static website hosting via REST API (`PUT /?website`) or the Huawei Cloud console.
 
+## Single-File Quick Share
+
+See `references/single-file-share.md` for the full workflow to host one file and get a shareable link in seconds:
+
+- **Private, time-limited**: `hcloud OBS sign obs://<bucket>/<key> -e=<seconds>` (max 7 days)
+- **Public, permanent**: `hcloud OBS cp <file> obs://<bucket>/<key> -f` + `hcloud OBS chattri obs://<bucket>/<key> -acl=public-read`, then share `https://<bucket>.obs.<region>.myhuaweicloud.com/<key>`
+
 ## Storage Classes
 
 | Class | Use Case | Min Storage | Retrieval Fee |
@@ -82,7 +99,7 @@ Build → Create bucket → Upload → Set bucket ACL → Set object ACL → Con
 | Error | Root Cause -> Fix |
 |-------|------------------|
 | AccessDenied on bucket | IAM/bucket policy/ACL conflict -> Check all three layers |
-| BucketAlreadyExists | Name taken globally -> Choose different name |
+| BucketAlreadyExists | Name taken globally -> Generate unique name with timestamp suffix: `{prefix}-{yyyymmddHHMMSS}` |
 | NoSuchKey | Object doesn't exist or wrong region -> Verify key and region |
 | InvalidAccessKeyId | OBS uses AK/SK directly -> Verify AK/SK validity, OBS endpoint, OBS permissions |
 | EntityTooLarge | Single PUT limit 5GB -> Use multipart upload |
@@ -105,5 +122,6 @@ Build → Create bucket → Upload → Set bucket ACL → Set object ACL → Con
 
 - OBS Docs: https://support.huaweicloud.com/obs/
 - Static website: references/static-website.md
+- Single-file share: references/single-file-share.md
 - Lifecycle: references/bucket-lifecycle.md
 - Replication: references/replication.md

package/plugins/huaweicloud-core/skills/huawei-obs/references/single-file-share.md

@@ -0,0 +1,40 @@
+# OBS Single-File Quick Share
+
+Host one file and get a shareable link in seconds. Two options:
+
+| Option | Link type | Bucket/object visibility | Expiry |
+|--------|-----------|--------------------------|--------|
+| Presigned URL | Time-limited private link | Keep private | `-e=<seconds>`, max 7 days |
+| Public URL | Permanent public link | Set object `-acl=public-read` | None |
+
+## Option 1: Presigned URL (private, time-limited)
+
+No ACL change needed. The object stays private; the link grants temporary access.
+
+```bash
+hcloud OBS cp <file> obs://<bucket>/<key> -f
+hcloud OBS sign obs://<bucket>/<key> -e=3600   # valid 1 hour, max 604800 (7 days)
+```
+
+The `sign` command prints the full presigned URL directly — share it as-is.
+
+## Option 2: Public URL (permanent, public-read)
+
+```bash
+hcloud OBS cp <file> obs://<bucket>/<key> -f
+hcloud OBS chattri obs://<bucket>/<key> -acl=public-read
+```
+
+The shareable public URL follows the OBS endpoint format (NOT the `obs-website` static-site endpoint):
+
+```
+https://<bucket>.obs.<region>.myhuaweicloud.com/<key>
+```
+
+## Key Gotchas
+
+- **Bucket ACL does NOT cascade**: `chattri obs://<bucket> -acl=public-read` alone does not make objects public. Set the object-level ACL explicitly.
+- **`-f` is mandatory**: `cp` without `-f` prompts "Please input (y/n)" on overwrite → agent hangs (TIMEOUT).
+- **Public-read means anyone with the link can access**: use presigned URLs when the file is sensitive.
+- **Presigned URL max expiry is 7 days** (`-e=604800`). For longer-lived public access, use the public-read option.
+- **Credential setup**: OBS uses a separate config (`~/.obsutilconfig`). Call `huaweicloud_setup_obs_config` before first use.