用途：面向 AI 智能体的 Medusa Cloud 基础设施操作指南，通过 mcloud CLI 完成初始化、部署、调试、环境与环境变量管理。
主要能力与约束：解析 CLI 输出时始终加 --json，纯文本输出仅供人阅读且可能变动。任何状态变更前先运行 mcloud whoami --json 确认上下文。删除、重新部署或触发构建前先执行 get 或 list。非交互模式下 delete 命令（含 variables delete）需要 --yes。变量变更需重新部署才生效：variables set/delete 不会重建或重新部署，运行时改动用 redeploy，构建改动用 trigger-build。生产环境不可删除，mcloud environments delete 对生产环境按设计报错。除非用户明确要求，绝不使用 --reveal。--json 与 --follow 不兼容，程序化日志采集请用 --from/--to 限定时间窗口。
必要用法：认证检查 mcloud whoami --json | jq -e '.auth.kind != "none" and .organization.id != null'；设置上下文 mcloud use --organization org_123 --project proj_123 --environment production，不带参数会进入交互模式，在 CI/Docker/管道输入中会失败，务必传参。部署状态按 backend_status（或 storefront_status）路由：build-failed 查 mcloud deployments build-logs <id>；deployment-failed 查 mcloud logs --deployment <id>；timed-out 先查构建日志再查运行时日志。redeploy 用于环境侧修复（变量、基础设施），复用现有构建；trigger-build 用于源码分支上的修复，启动新构建。
参考文件：初始化 CLI 前须加载 setup.md；调试失败部署前须加载 debugging-deployments.md；管理环境或变量前须加载 environments-and-variables.md。多步工作流至少先加载一个参考文件。
常见陷阱：mcloud login、不带参数的 mcloud use、不带 --yes 的 delete 都需要 TTY，在 CI、Docker 或管道输入中会失败。设置 MCLOUD_TOKEN 时会忽略文件凭据并拒绝 mcloud login，切换账号需先取消该变量。个人密钥需要 --organization，组织密钥已预置作用域；organizations list 需要个人认证，组织密钥会返回 401。depl_* 为部署 ID，其他为构建 ID（解析为最新部署）。mcloud local build 无 --json，以纯文本流式输出并通过退出码报告成功（0 为成功），需要 Docker 且须在项目 Git 仓库内运行。