@clickzetta/cz-cli-darwin-x64 0.3.74 → 0.3.76

package/bin/skills/clickzetta-dynamic-table/sql-to-dt/references/sql2dt-workflow.md

@@ -0,0 +1,109 @@
+# SQL → Dynamic Table 完整转换工作流
+
+当用户给你一组 CREATE TABLE DDL 和 INSERT OVERWRITE SQL，要求转换为 Dynamic Table 时，按以下步骤顺序执行。
+
+每一步的详细规则在对应的 skill 文件中，你需要同时引用它们。
+
+## 工作流步骤
+
+### Step 1: 预处理输入
+
+从 INSERT OVERWRITE 文件中移除：
+- 所有 `ALTER TABLE` 语句
+- `ANALYZE TABLE` 语句
+- SQL 注释（`--` 和 `/* */`）
+
+保留：CREATE TABLE、INSERT OVERWRITE、WITH、SET、CREATE TEMPORARY FUNCTION。
+
+### Step 2: 占位符替换
+
+按 #[[file:sql2dt-placeholder-rules.md]] 中的规则：
+1. 统一占位符格式（`{{ }}` → `${ }`）
+2. 替换所有占位符为 `SESSION_CONFIGS()` 调用
+3. 处理 nodash 变量、日期运算、macros 函数
+4. 根据引号上下文决定处理方式（去引号 / CONCAT / 直接替换）
+
+### Step 3: 自引用检测
+
+按 #[[file:sql2dt-self-reference-rules.md]] 中的规则：
+1. 检查 INSERT OVERWRITE 目标表是否出现在 FROM/JOIN 中
+2. 如果是自引用表，标记并在后续步骤中添加注释、使用显式 schema
+
+### Step 4: 核心转换
+
+按 #[[file:sql2dt-conversion-rules.md]] 中的规则：
+1. 解析 CREATE TABLE DDL（提取列、分区、属性等）
+2. 解析 INSERT OVERWRITE（提取查询、分区类型）
+3. 组装 `CREATE OR REPLACE DYNAMIC TABLE ... AS SELECT ...`
+4. 注入静态分区值到 SELECT（智能引号处理）
+5. 合并表属性模板（默认 `data_lifecycle=15`）
+6. 处理 UNION ALL（每个分支独立注入）
+7. 日期函数后处理：将所有 `DATE_SUB/DATE_ADD` 统一转为 `sub_days`
+
+### Step 5: 列校验
+
+按 #[[file:sql2dt-column-validation-rules.md]] 中的规则：
+1. 计算 schema 列数和 SELECT 列数
+2. 验证两者相等
+3. 检查重复别名和缺失分区列
+4. UNION ALL 分支列数一致性检查
+
+### Step 6: 生成配套文件
+
+按 #[[file:sql2dt-refresh-rules.md]] 中的规则：
+1. 从 DDL 中提取所有 SESSION_CONFIGS 变量
+2. 生成当前周期 refresh 语句
+3. 生成上一周期 prev_refresh 语句
+4. 生成回填 backfill 语句
+
+### Step 7: 转换后改进建议
+
+DDL 生成完成后，对转换结果做以下检查，并主动向用户提出改进建议：
+
+**检查 1：非分区表 + 持续写入风险**
+
+按 #[[file:../best-practices/non-partitioned-merge-into-warning.md]] 中的判断逻辑：
+- 生成的 DT 是非分区表（无 `PARTITIONED BY` 也无 `SESSION_CONFIGS()`）
+- 且 SQL 中包含 `ROW_NUMBER() OVER (PARTITION BY ... ORDER BY ... DESC) WHERE rn = 1` 去重模式
+
+→ 满足条件时，使用该文档中的告警话术模板向用户发出风险提示，并建议改用 MERGE INTO + Table Stream 方案。
+
+**检查 2：SQL 性能优化机会**
+
+按 #[[file:../best-practices/performance-optimization.md]] 中的规则，扫描生成的 DT SQL：
+- 存在 `LEFT/RIGHT/FULL OUTER JOIN` → 提示如果业务允许，改用 INNER JOIN 可提升增量效率
+- 存在无 `PARTITION BY` 的窗口函数 → 提示添加 PARTITION BY，否则每次增量都全量重算
+- `GROUP BY` 使用了复杂表达式（如 `DATE_TRUNC`、`SUBSTR`）→ 提示考虑在上游预计算或拆分为多级 DT
+
+**检查 3：JOIN 中是否有维度表**
+
+按 #[[file:../best-practices/dimension-table-join-guide.md]] 中的推荐场景：
+- SQL 中存在 JOIN → 询问用户右侧表是否为低频变更的维度表（码表、字典表、配置表等）
+- 如果是 → 建议在 TBLPROPERTIES 中添加 `mv_const_tables` 配置，并说明其行为和数据一致性权衡
+
+## 输出清单
+
+对每个表，最终输出：
+
+| 文件 | 内容 | 条件 |
+|------|------|------|
+| `表名.sql` | Dynamic Table DDL | 始终生成 |
+| `表名_refresh.sql` | 当前周期 REFRESH 语句 | 始终生成 |
+| `表名_prev_refresh.sql` | 上一周期 REFRESH 语句 | 仅有分区变量时 |
+| `表名_backfill.sql` | 回填语句 | 仅有分区变量时 |
+
+## 快速判断路径
+
+```
+输入 DDL + INSERT OVERWRITE
+  │
+  ├─ 有占位符？ → Step 2 占位符替换
+  │
+  ├─ 自引用？ → Step 3 特殊处理
+  │
+  ├─ 有静态分区？ → Step 4 注入分区值到 SELECT
+  │
+  ├─ 有 UNION ALL？ → Step 4 每个分支独立注入
+  │
+  └─ 生成 DDL → Step 5 校验 → Step 6 生成配套文件 → Step 7 改进建议
+```

package/bin/skills/cz-cli/SKILL.md

@@ -1,274 +1,312 @@
 ---
 name: cz-cli
-description: "CLI tool for ClickZetta Lakehouse. Use this skill when the user needs to run SQL queries, develop or schedule Studio tasks, check run status and logs, or manage tables and schemas."
-generated_cli_version: "0.0.0-dev+202605250308"
-generated_with: "cz-cli-skill-generator/1.0.0"
-command_inventory_source: "click-command-tree"
-command_count: 51
+description: "Route ALL ClickZetta Lakehouse operations to cz-cli: SQL, Studio tasks, tables, pipelines, profiles. Use when user mentions ClickZetta, Lakehouse, cz-cli, or needs profile/connection configuration."
 ---
 
-# cz-cli Skill
+# cz-cli — ClickZetta Lakehouse Subagent
 
-> [!IMPORTANT]
-> **Fallback**: If `cz-cli` command not present, check for a bundled binary at `scripts/<platform>/cz-cli` (e.g. `scripts/macos-arm64/cz-cli`, `scripts/linux-x86_64/cz-cli`, `scripts/windows-x86_64/cz-cli.exe`). If found, use its absolute path directly. Otherwise run `pip3 install cz-cli -U` then use `cz-cli` from PATH.
+You have no direct Lakehouse access. Always delegate via cz-cli.
 
-## AI Agent Behavior Rules
+## Capabilities
 
-> [!IMPORTANT]
-> Read these rules before invoking any command.
+### SQL & Data Operations
+- Execute any SQL against Lakehouse: SELECT, DDL (CREATE/ALTER/DROP TABLE, SCHEMA, VIEW), DML (INSERT, UPDATE, DELETE, MERGE INTO)
+- Run async jobs and fetch results
+- Preview table data and row counts
 
-### Rule 0 — Initialize connection profile before first use
+### Table & Schema Management
+- List, describe, create, and drop tables and schemas
+- View table history, indexes, partitions, and statistics
+- Add or update column/table comments
+- Create Dynamic Tables for auto-incremental ETL (ODS→DWD→DWS pipelines)
+- Create Materialized Views for pre-computed aggregations
+- Create Table Streams to capture INSERT/UPDATE/DELETE changes for CDC UPSERT
 
-When any command returns error code `NO_PROFILE`, run `cz-cli setup --credential <base64>` if the credential string is available, or read `references/profile-setup.md` and follow the onboarding steps there. Always use the **AskUserQuestion tool** — never ask via plain text.
+### Studio Task Management
+- Create, configure, deploy, and delete Studio tasks (SQL, Shell, Python, integration, flow)
+- Save task content and cron schedule
+- Deploy, undeploy, and execute tasks ad-hoc
+- Monitor run instances: list, detail, wait, logs, stop, rerun, backfill
+- View run statistics and dependencies
 
-### Rule 1 — Clarify intent before any state-changing operation
+### Data Sync Pipelines
+- Create single-table realtime CDC sync tasks (MySQL/PostgreSQL/SQL Server → Lakehouse, task_type=28)
+- Create multi-table or whole-database CDC sync tasks — mirror, merge, or sharded-table consolidation (task_type=281)
+- Create offline batch sync tasks with Cron scheduling — single-table (task_type=10) or multi-table (task_type=291)
+- Manage sync task lifecycle: start, stop, offline, backfill, add tables, re-sync individual tables
 
-When a task involves an operation that changes system state (publishing a schedule, taking a task offline, triggering a run, deleting an object, etc.):
+### Data Ingestion Pipelines
+- Create continuous OSS/S3/COS ingest PIPE (LIST_PURGE scan mode or EVENT_NOTIFICATION mode)
+- Create continuous Kafka ingest PIPE using READ_KAFKA function
+- One-shot file import from URL, local path, or Volume (COPY INTO)
+- Manage PIPE lifecycle: pause, resume, adjust batch interval, view load history
 
-**Do NOT proceed without** explicitly understanding the user's intent on all three points:
-1. **Target**: Which task / table / run instance?
-2. **Purpose**: Why does this need to happen now?
-3. **Side-effect acknowledgment**: Does the user understand the impact (historical re-runs, schedule interruption, permanent deletion, etc.)?
+### Data Recovery
+- Query data at a historical point in time (Time Travel: TIMESTAMP AS OF)
+- Roll back a table to a previous version (RESTORE TABLE)
+- Recover accidentally dropped tables, dynamic tables, or materialized views (UNDROP TABLE)
+- Inspect change history (DESC HISTORY) and deleted objects (SHOW TABLES HISTORY)
+- Configure retention: data_retention_days, data_lifecycle
 
-Use the **AskUserQuestion tool** (not plain text) to confirm with the user, then wait for an explicit reply before executing.
+### Connection & Environment Management
+- Create, update, delete, and switch connection profiles (multi-cloud, multi-region)
+- Check connection status and switch workspace
+- List and test external data sources, browse catalogs and objects
+- Generate Python SDK / ZettaPark / SQLAlchemy / JDBC connection code from profile parameters
 
-Consult **Command Risk Reference** below to determine whether a command qualifies as state-changing.
+## Route to cz-cli
 
+- Any mention of cz-cli, ClickZetta, or Lakehouse
+- SQL against Lakehouse (SELECT, DDL, DML)
+- Studio task development, scheduling, monitoring
+- Data pipelines (sync, import, CDC, streaming)
+- Profile and connection configuration
+- Performance analysis and optimization
 
-### Rule 2 — Route to companion skill BEFORE acting (MUST)
+## Keep in host agent
 
-> [!IMPORTANT]
-> Check this routing table **before** executing any command or writing any code.
-> If the user intent matches a trigger below, **MUST** invoke the listed skill immediately and stop processing in cz-cli.
+- General programming unrelated to ClickZetta
+- Local file operations, git
+- Non-ClickZetta databases (PostgreSQL, MySQL standalone)
 
-The following companion skills are bundled with `cz-cli`:
+## Execution strategy
 
-- **lakehouse-python-sdk** — Lakehouse Python/Shell task engineering: develop, rewrite, optimize, troubleshoot. Covers connector, BulkLoad, IGS, Studio params, datasource, and CREATE TABLE DDL; MUST trigger on: develop/write/create/modify/rewrite/optimize Python or Shell task; BulkLoad batch upload; IGS realtime ingest; connector query/write; Python task error/diagnosis; CREATE TABLE / partition / bucket / index DDL.
-- **lakehouse-doc** — ClickZetta Lakehouse official documentation. Covers SQL syntax, data types, functions, DDL/DML commands, dynamic tables, materialized views, access control, VCluster, data lake, AI functions, etc. When the user writes or asks about SQL syntax or Lakehouse dialect specifics, **MUST** consult lakehouse-doc skill references first to ensure accuracy.
+**MANDATORY: Follow this order every time. No exceptions.**
 
-**If no row matches**: proceed with cz-cli commands directly.
+**Step 1 — MUST check LLM first:**
 
-### Rule 2.1 — MUST consult lakehouse-doc skill for SQL commands
+```bash
+cz-cli agent llm show
+```
+
+**Step 2 — If active LLM is configured (kind != "none"), you MUST use agent run:**
+
+```bash
+cz-cli agent run "<request>" --format a2a --dangerously-skip-permissions
+```
+
+Do NOT use direct cz-cli subcommands when an active LLM is available. Always delegate the full request to `cz-cli agent run`.
+
+The output includes a `session_id`. Use it to inspect the run:
+- `cz-cli agent session status <session_id>` — current state (`busy`/`retry` with `progress`, `idle` with `result`, or `error`)
+- `cz-cli agent export <session_id>` — full conversation (messages, tool calls, reasoning, text). Wait until `status` is `idle` before exporting; otherwise the conversation may still be in progress.
+
+**Step 3 — ONLY if no active LLM (kind: "none" or empty list), fall back to direct commands:**
+
+Decompose the request into concrete `cz-cli` subcommands (`sql`, `schema`, `table`, `task`, `runs`, `job`, `datasource`, `profile`, etc.), execute them, and synthesize the result.
+
+Use direct commands for local setup and diagnostics even when agent path is available: `cz-cli profile ...`, `cz-cli -p <profile> status`, `cz-cli agent llm ...`, `cz-cli --help`.
+
+With session continuity:
+
+```bash
+cz-cli agent run "<request>" --format a2a --dangerously-skip-permissions --session <session_id>
+```
+
+Reuse `session_id` for follow-ups on the same topic. Omit `--session` to start fresh.
+
+## Async mode (non-TTY / long-running tasks)
+
+When running in non-TTY environments (e.g. as a subagent from Claude Code) or for long-running tasks, use async mode to avoid blocking:
+
+### Submit asynchronously
+
+```bash
+cz-cli agent run "<request>" --async --format a2a --dangerously-skip-permissions
+```
+
+Returns immediately with a session ID:
+```json
+{"session_id": "01JXF3K...", "status": "running", "message": "Session submitted asynchronously"}
+```
+
+Note: In non-TTY with `--format a2a` or `--format json`, async mode activates automatically (no `--async` flag needed).
+
+### Poll status
+
+```bash
+cz-cli agent session status <session_id>
+```
+
+While running:
+```json
+{"session_id": "01JXF3K...", "status": "busy", "progress": "$ cz-cli table list -o table"}
+```
+
+Other progress examples you may see during polling:
+- `"💭 Thinking..."` — LLM is reasoning
+- `"✏ Generating response..."` — LLM is writing the reply
+- `"✱ Grep \"error\" · 3 matches"` — running a search tool
+- `"↻ Retry (attempt 2)"` — retrying a failed LLM call (paired with a `retry` field describing the reason)
+
+When complete:
+```json
+{"session_id": "01JXF3K...", "status": "idle", "result": "Here are the results:\n..."}
+```
+
+The `result` field is the final text reply. For full conversation details (thinking, tool calls, intermediate text), use `cz-cli agent export <session_id>`.
+
+If the session does not exist:
+```json
+{"session_id": "ses_invalid", "error": "Session not found"}
+```
+(exits with code 1)
+
+### Retrieve full conversation (thinking + tool calls + text)
+
+```bash
+cz-cli agent export <session_id>
+```
+
+Returns complete session with all message parts:
+```json
+{
+  "info": { "id": "...", "title": "...", "time": {...} },
+  "messages": [
+    {
+      "info": { "role": "user" },
+      "parts": [{ "type": "text", "text": "original prompt" }]
+    },
+    {
+      "info": { "role": "assistant" },
+      "parts": [
+        { "type": "reasoning", "text": "thinking content..." },
+        { "type": "tool", "tool": "bash", "state": { "status": "completed", "input": {...}, "output": "..." } },
+        { "type": "text", "text": "final answer..." }
+      ]
+    }
+  ]
+}
+```
+
+Part types in export:
+- `reasoning` — LLM thinking/reasoning blocks
+- `tool` — tool calls with full input/output (bash, read, write, edit, glob, grep, etc.)
+- `text` — final text response
+- `step-start` / `step-finish` — step boundaries
+- `patch` — code diffs
+- `subtask` — delegated sub-tasks
+
+### Async workflow pattern
 
-When the user request involves any of the following, **MUST** consult **lakehouse-doc** skill references before answering or generating SQL:
+```bash
+# 1. Submit
+SESSION=$(cz-cli agent run "complex analysis" --async --format a2a --dangerously-skip-permissions | jq -r '.session_id')
+
+# 2. Poll until done, printing progress along the way
+while true; do
+  STATUS=$(cz-cli agent session status $SESSION)
+  STATE=$(echo "$STATUS" | jq -r '.status')
+  if [ "$STATE" = "idle" ]; then
+    echo "$STATUS" | jq -r '.result'
+    break
+  fi
+  echo "$STATUS" | jq -r '.progress // empty'
+  sleep 5
+done
+
+# Need full conversation (thinking + tool calls)?
+cz-cli agent export $SESSION
+```
 
-- Writing, modifying, or optimizing SQL statements (DDL / DML / DQL)
-- Asking about ClickZetta Lakehouse SQL dialect syntax, keywords, or function usage
-- Using data types, type casting, or datetime formats
-- Creating or altering tables, views, materialized views, dynamic tables, external tables
-- Data import/export (COPY INTO, PUT/GET, BulkLoad, Pipe)
-- Access control (GRANT / REVOKE), roles, permissions
-- VCluster configuration and management
-- Index creation and usage (inverted index, BloomFilter, vector index)
-- AI functions, vector search, semantic views
-- Information Schema system view queries
+### With session continuity (async)
 
-**Rationale**: ClickZetta Lakehouse SQL dialect differs from standard SQL and other databases. Relying on general knowledge may produce incorrect syntax. Consulting lakehouse-doc significantly improves answer accuracy and confidence.
+```bash
+# First turn
+SESSION=$(cz-cli agent run "describe sales table" --async --format a2a --dangerously-skip-permissions | jq -r '.session_id')
+# ... wait for completion ...
 
-### Rule 3 — Development ends at save; execution requires separate authorization
+# Follow-up turn on same session
+cz-cli agent run "now show row counts" --async --format a2a --dangerously-skip-permissions --session $SESSION
+```
 
-When the user says "develop", "write", "create", or "modify" a task, the work is **complete once the script is saved successfully**.
-After saving, tell the user: "The task has been saved as a draft. Scheduling is not yet active. Let me know explicitly if you want to publish or execute it."
+### Important notes for async mode
 
-**Do NOT** auto-publish, auto-trigger execution, or auto-submit a backfill after saving — even if those steps seem like the logical next thing. Every phase that produces a real side effect requires the user to express intent and grant authorization separately.
+- **Permissions:** Always use `--dangerously-skip-permissions` — async mode cannot handle interactive permission prompts
+- **Server requirement:** An agent runtime server must be running (or will be started automatically)
+- **Error handling:** If session is already busy, returns `{"error": "session busy"}`
 
-**Exception**: If the user's original request *explicitly* authorized all subsequent steps (e.g. "create and immediately go live", "develop and run it now"), AND Rule 1 already confirmed that intent at the start, the Agent may proceed through the authorized steps without stopping again at each phase. Do not re-ask for confirmation that was already given.
+## Multi-environment (profiles)
 
-### Rule 3.1 — 补数/回填/重跑历史数据 → `runs refill` (NOT `task`)
+When the user specifies an environment or profile (e.g. "use uat_test", "on the test instance"):
 
-When the user says "补数", "回填", "重跑历史", "backfill", "re-run historical", or "re-process date range":
-- **MUST** use `cz-cli runs refill <task> --from YYYY-MM-DD --to YYYY-MM-DD [-y]`
-- This command is under `runs`, **NOT** under `task` — do not look for it in task subcommands
-- Requires the task to already be published (online); draft tasks cannot be backfilled
+```bash
+cz-cli agent run "<request>" --profile uat_test --format a2a --dangerously-skip-permissions
+```
 
-### Rule 4 — Paginated results are not complete data
+Available profiles: read `~/.clickzetta/profiles.toml` or run `cz-cli profile list`.
 
-All `list` commands return only page 1 by default (typically 10 items). The `ai_message` field in the response contains the total count and the command to fetch the next page — treat it as the authoritative next-step hint and follow it. Never treat a first-page result as the full dataset.
+## Adding a new profile
 
-**Pagination termination rules**:
-- If the user only needs "latest / recent N items": stop after page 1, do not paginate.
-- If the user needs the full dataset: paginate until `ai_message` no longer contains a next-page hint.
-- **Safety limit**: auto-paginate at most **3 pages** (≈ 30 items). If more exist, surface the next-page command to the user and ask whether to continue.
+**Trigger conditions:** User says "configure new environment", "add profile", "can't connect", mentions an unknown profile name, or provides connection credentials.
 
-### Rule 5 — Always pass explicit task type when creating tasks
+### Step 1 — Collect information (guided Q&A)
 
-When creating a task with `cz-cli task create`, **always** pass `--type` explicitly (`SQL` / `PYTHON` / `SHELL` / `SPARK` / `FLOW`).
-The Python SDK(connector/igs/bulkload) is using from clickzetta import connect instead of Zettapark's session.
+If all required fields are already provided, skip directly to Step 2.
 
-- **MUST NOT** rely on default task type.
-- If user intent says “Python task”, command must include `--type PYTHON`.
-- If `--type FLOW`, immediately switch to Rule 6 — use Flow-specific commands exclusively.
+Otherwise, ask for missing ones. Accept all at once or prompt one by one.
 
-### Rule 6 — Flow nodes use Flow-specific tools exclusively
+**Required fields:**
 
-When the operation target is a Flow task or any of its child nodes (`task_type=500`, or user mentions "composite task / flow / workflow"):
+| Field | Question to ask | Example |
+|-------|----------------|---------|
+| `service` | Which cloud region? (see table below, or provide the service endpoint directly) | `cn-shanghai-alicloud.api.clickzetta.com` |
+| `instance` | What is the instance name? | `billingsh` |
+| `workspace` | What is the workspace name? | `meter_n_bill` |
+| `username` | What is the username? | `billing_admin` |
+| `password` | What is the password? | — |
+| `name` | What should this profile be named? (suggested format below) | `billingsh` |
 
-- **MUST** use Flow-specific commands: `task flow node-detail`, `task flow node-save`, `task flow node-save-config`, `task flow bind`, `task flow submit`, etc.
-- **MUST NOT** use `task save`, `task save-config`, `task detail`, or `task online` on Flow child nodes — these tools are for regular (non-Flow) tasks only and will produce incorrect results or errors.
-- **Decision rule**: if `task_type == 500` OR the user mentions flow/workflow context → use `task flow *` commands unconditionally.
+**Common service endpoints (offer as options):**
 
-### Rule 7 — Always display studio_url in final report
+| Region | service | Suggested profile prefix |
+|--------|---------|--------------------------|
+| Alibaba Cloud East China 2 (Shanghai) | `cn-shanghai-alicloud.api.clickzetta.com` | `cn-shanghai` |
+| Tencent Cloud East China (Shanghai) | `ap-shanghai-tencentcloud.api.clickzetta.com` | `ap-shanghai` |
+| Tencent Cloud North China (Beijing) | `ap-beijing-tencentcloud.api.clickzetta.com` | `ap-beijing` |
+| Tencent Cloud South China (Guangzhou) | `ap-guangzhou-tencentcloud.api.clickzetta.com` | `ap-guangzhou` |
+| AWS China (Beijing) | `cn-north-1-aws.api.clickzetta.com` | `cn-north-1` |
 
-Responses from `task`, `runs`, and `executions` commands may include a `studio_url` field. When present, surface it in the end to the user so they can open the resource directly in Studio.
+**Inference rules (reduce unnecessary questions):**
+- If the user describes a cloud region in natural language (e.g. "Alibaba Cloud Shanghai", "Tencent Cloud Beijing", "阿里云上海", "腾讯云北京"), look up the service endpoint from the table above — do NOT ask the user to provide it again.
+- If the user hasn't provided a profile name, suggest `<prefix>-<instance>` using the prefix from the table (e.g. `cn-shanghai-billingsh`). Confirm with the user or proceed if they don't object.
 
-Display as a Markdown hyperlink: `[View in Studio](https://...)`. Show all studio_url values returned across all commands in the same response — do not deduplicate.
+### Step 2 — Create profile
 
-### Rule 8 — Maximize execution efficiency: parallel and chained commands
+Run `cz-cli profile create` with all collected fields:
 
-**Independent commands → parallel.  Dependent commands → chain with `--field`.**
+```bash
+cz-cli profile create <name> \
+  --username <username> \
+  --password <password> \
+  --instance <instance> \
+  --workspace <workspace> \
+  --service <service> \
+  --schema public \
+  --vcluster default
+```
+
+### Step 3 — Verify connection
+
+After creating, run:
 
 ```bash
-# Async SQL: submit → poll → fetch result → preview first rows
-JOB=$(cz-cli sql "SELECT * FROM orders LIMIT 100" --field job_id) && cz-cli job status $JOB --format toon && cz-cli job result $JOB --format toon | head -12
+cz-cli status --profile <name>
+```
+
+A successful response looks like:
+```json
+{"data": {"connected": true, "workspace": "...", "time_ms": ...}}
+```
+
+If it fails, report the error and ask the user to double-check credentials or service endpoint.
+
+## Error handling
 
-# Parallel: two independent lookups at the same time
-cz-cli task content my_task --format toon & cz-cli runs list --task my_task --format toon & wait
+All errors in non-TTY mode output JSON to stdout:
 
-# Chain: save then verify
-cz-cli task save-content my_task --file script.sql && cz-cli task content my_task --format toon
+```json
+{"ok": false, "error": "NO_PROFILE", "next_steps": ["cz-cli setup --credential <base64>"]}
 ```
 
-Key tools:
-- `--field <name>` — extract one value as raw text: `cz-cli sql "..." --field job_id` → `2026042818122957849079780`
-- `--format toon` — line-per-field output, works with `grep`/`head`
-- `--format json` — single-line JSON, parse in code only (do NOT pipe to grep/head)
-
-**Shortcut**: Use `cz-cli sql --sync "..." > /tmp/res.json` to force synchronous execution (waits for results inline). Prefer `--sync` for simple/fast queries.
-
-## Command Quick Reference
-
-### Connection & Profile
-- `cz-cli profile create <name> --username U --password P --instance I --workspace W` — Create profile
-- `cz-cli profile create <name> --pat TOKEN --instance I --workspace W` — Create profile with PAT
-- `cz-cli profile list` — List all profiles
-- `cz-cli profile status` — Test connection, show workspace/schema
-- `cz-cli profile use <name>` — Set default profile
-- `cz-cli profile delete <name>` — Delete a profile
-- `cz-cli profile discover --studio-url URL --username U --password P` — Discover regions/instances
-
-### SQL Execution
-- `cz-cli sql "SELECT * FROM t LIMIT 10"` — Execute SQL query
-- `cz-cli sql -f query.sql` — Execute SQL from file
-- `cz-cli sql --write "INSERT INTO t VALUES (...)"` — Write operation (requires --write)
-- `cz-cli sql --async "SELECT count(*) FROM big_table"` — Async execution, returns job_id
-- `cz-cli sql --sync "SELECT 1"` — Force synchronous execution
-- `cz-cli sql -e "SELECT * FROM t WHERE id = %(id)s" --variable id=123` — Variable substitution
-
-### Job Management (async SQL results)
-- `cz-cli job status <job_id>` — Check job status
-- `cz-cli job result <job_id>` — Fetch result set (waits if running, limited to 100 rows)
-- `cz-cli job result --no-limit <job_id>` — Fetch full result set
-
-### Schema & Table
-- `cz-cli schema list` / `cz-cli schema describe <name>` / `cz-cli schema create <name>` / `cz-cli schema drop <name>`
-- `cz-cli table list [--schema S] [--like 'pattern%']` / `cz-cli table describe <name>` / `cz-cli table preview <name> [--limit N]`
-- `cz-cli table stats <name>` / `cz-cli table history [name]` / `cz-cli table create "DDL"` / `cz-cli table drop <name>`
-
-### Workspace
-- `cz-cli workspace current` — Show current workspace
-- `cz-cli workspace use <name> [--persist]` — Switch workspace
-
-### Task Scheduling (Studio)
-- `cz-cli task list [--page N --page-size N]` — List tasks
-- `cz-cli task create <name> --type SQL|PYTHON|SHELL|SPARK|FLOW --folder F` — Create task
-- `cz-cli task content <name_or_id>` — Get task script, config and params (draft); response includes `params` array with `paramType=system` (built-in params / time expressions) or `paramType=manual` (constants)
-- `cz-cli task save-content <name_or_id> --file script.sql [--params '{"key":"val","dt":"bizdate","yd":"$[yyyy-MM-dd,-1d]"}']` — Save script and optionally set params; system params (bizdate, sys_biz_day, sys_biz_datetime, sys_plan_day, sys_plan_datetime, sys_plan_timestamp, sys_task_id, sys_task_name, sys_task_owner) and time expressions starting with `$[` are auto-detected as `paramType=system`
-- `cz-cli task save-config <name_or_id> --cron "0 0 8 * * ? *"` — Save schedule (sec min hour day month week year)
-- `cz-cli task online <name_or_id> -y` — Publish task
-- `cz-cli task offline <name_or_id> -y` — Take offline (IRREVERSIBLE)
-- `cz-cli task execute <name_or_id> [--param KEY=VAL ...]` — Ad-hoc execution; auto-loads saved `manual` params as defaults (system params like `bizdate` are NOT auto-injected in adhoc mode — pass them explicitly via `--param`); warns if unresolved `${placeholders}` remain after merge (SQL tasks will fail, Python/Shell silently keep literal strings)
-- `cz-cli task flow dag <flow>` / `task flow create-node` / `task flow bind` / `task flow submit` — Flow operations
-
-### Runs & Attempts
-- `cz-cli runs list [--task T --status S --run-type SCHEDULE|REFILL --from D --to D]`
-- `cz-cli runs detail <run_id_or_task>` / `cz-cli runs logs <run_id_or_task>` / `cz-cli runs wait <id> --timeout N`
-- `cz-cli runs refill <task> --from D --to D [-y]` — **补数/回填**: re-run scheduled instances for a historical date range (task must be online). `D` accepts `YYYY-MM-DD` (day boundary: `--from` = start of day, `--to` = 23:59:59) or `YYYY-MM-DDTHH:MM:SS` for exact datetime — **use ISO datetime for hourly/minutely tasks** to avoid missing instances
-- `cz-cli attempts list <run_id_or_task>` / `cz-cli attempts log <run_id_or_task> [--attempt-id N]`
-
-### Agent (AI Agent)
-- `cz-cli agent run "<prompt>" [--session ID]` — Run AI agent with a natural-language prompt
-- `cz-cli agent llm` — Manage LLM providers
-
-## Command Inventory (Generated)
-
-### `ai-guide`
-- `ai-guide` - Generate AI-friendly command reference
-
-### `attempts`
-- `attempts` - Manage attempt records
-- `attempts list` - List attempts for a run
-- `attempts log` - Get attempt log
-
-### `job`
-- `job` - Job performance tools
-- `job result` - Fetch result set of a SQL job
-- `job status` - Check status/summary of a SQL job
-
-### `profile`
-- `profile` - Manage connection profiles
-- `profile create` - Create a profile
-- `profile delete` - Delete a profile
-- `profile detail` - Show profile details
-- `profile list` - List profiles
-- `profile update` - Update a profile
-- `profile use` - Set default profile
-
-### `runs`
-- `runs` - Manage task run instances
-- `runs deps` - View run dependencies
-- `runs detail` - Get run detail
-- `runs list` - List run instances
-- `runs logs` - Get run logs
-- `runs refill` - Submit backfill job
-- `runs rerun` - Rerun a failed instance
-- `runs stats` - Get run statistics summary
-- `runs stop` - Stop a running instance
-- `runs wait` - Poll until run completes
-
-### `schema`
-- `schema` - Manage schemas
-- `schema create` - Create a schema
-- `schema describe` - Describe a schema
-- `schema drop` - Drop a schema
-- `schema list` - List schemas
-
-### `sql`
-- `sql` - Execute SQL against ClickZetta
-  - `cz-cli sql "SELECT 1"` — Run a simple query
-  - `cz-cli sql -e "SELECT * FROM t LIMIT 10" --sync` — Synchronous query
-  - `cz-cli sql -f query.sql --write` — Execute write SQL from file
-
-### `table`
-- `table` - Manage tables
-- `table create` - Create a table from DDL
-- `table describe` - Describe a table
-- `table drop` - Drop a table
-- `table history` - Show table history
-- `table list` - List tables
-- `table preview` - Preview table data
-- `table stats` - Get table row count
-
-### `task`
-- `task` - Manage Studio tasks
-- `task content` - Get task content
-- `task create` - Create a new task
-- `task deps` - Show task dependencies
-- `task execute` - Execute a task ad-hoc
-- `task list` - List tasks
-- `task offline` - Take a task offline
-- `task online` - Publish a task
-- `task save-config` - Save task schedule config
-- `task save-content` - Save task script
-
-### `workspace`
-- `workspace` - Manage workspaces
-- `workspace current` - Show current workspace
-- `workspace list` - List workspaces
-
-## Command Risk Reference
-
-| Risk Level      | Commands                                         | Key Concern                                                     |
-|-----------------|--------------------------------------------------|-----------------------------------------------------------------|
-| 🔴 Irreversible | `task offline`, `schema drop`, `table drop`      | Cannot be undone; clears history or deletes objects permanently |
-| 🟠 High Impact  | `task online`, `runs refill`, `task flow submit` | Affects live schedule or re-runs historical data                |
-| 🟢 Safe         | All others                                       | No side effects                                                 |
+On `NO_PROFILE` error: check if a profile can be configured via username/password (see "Adding a new profile" above). If the user has a base64 credential instead, guide them to run `cz-cli setup --credential <base64>`. See `references/profile-setup.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clickzetta/cz-cli-darwin-x64",
-  "version": "0.3.74",
+  "version": "0.3.76",
   "description": "cz-cli binary for macOS x64 (Intel)",
   "os": [
     "darwin"