@lark-project/meegle 0.0.17 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+post-release changes accumulate under `[Unreleased]` and graduate to a
+versioned section on each npm release.
+
+## [Unreleased]
+
+## [v1.0.1] - 2026-04-28
+
+### Added
+
+- New `attachment` domain exposing Lark project's two-stage attachment protocol — basic `attachment prepare-upload` / `attachment prepare-download` for raw signed-URL preprocess payloads, and end-to-end shortcuts `attachment +upload` / `attachment +download` that chain the preprocess with the signed HTTP transfer client-side. Supports four resource types via `--resource-type`: `15` (workitem attachment field), `16` (rich-text field image), `13` (comment attachment), `14` (comment image); use `--work-item-id` for existing workitems and `--work-item-type` for the create-with-attachment path
+- `meegle url decode` subcommand for parsing Meego URLs into structured fields, including trailing-wildcard URL rules and a `setting_other` fallback for unknown views
+- `--params @file.json` syntax on every dynamic command so complex JSON payloads can be loaded from a file instead of a shell-escaped string
+- `--refresh` global flag forces a fresh tool-schema discovery, bypassing the `~/.meegle/cache/tools.json` cache; `auth login` now also invalidates the cache so the next invocation picks up the new identity's command set
+
+### Fixed
+
+- Tool-schema cache now honors its 24h `DefaultTTL`. Previously `resolveTools` returned any cache hit regardless of age, so server-side schema changes (new flags, renamed parameters, new commands) only surfaced after manually deleting `~/.meegle/cache/tools.json`. A stale cache now triggers a fresh discovery, falling back to the stale snapshot only when the server is unreachable so offline users keep their last-known command set
+- `meegle auth status` and the first-run auth check now route through the same `ResolveIdentity` path as runtime commands, so config-file tokens, env-var tokens, and store-backed tokens are treated consistently
+- The OS-native credential store (macOS keychain, Linux `secret-tool`, Windows DPAPI) is now wrapped in a `FallbackStore` that transparently switches to the encrypted file store on the first runtime Save/Load failure — fixes the silent token-loss in sandboxed macOS, locked-keychain SSH sessions, and headless Linux containers reported in [larksuite/meegle-cli#3](https://github.com/larksuite/meegle-cli/issues/3) without writing a sentinel probe entry to the user's keychain on every CLI invocation
+- `SecretToolStore.Load` no longer treats libsecret's "item absent from keyring" exit (exit 1, empty stdout, empty stderr) as a primary-store failure, so a fresh Linux user's first CLI run no longer permanently flips `FallbackStore` to the encrypted file store
+- Failed token-store writes after a successful refresh are no longer silently dropped — a stderr warning is emitted so the next CLI invocation does not silently re-trigger a 401 / re-login loop
+
+## [v1.0.0] - 2026-04-22
+
+Initial public release of Meegle CLI, published on npm as `@lark-project/meegle`.
+
+### Highlights
+
+- **Broad coverage** — 12 business domains and 40+ commands across work items, workflow, subtasks, comments, work hours, relations, my-work, views, charts, team, user, and project
+- **Agent-native** — bundled AI Agent Skill for Trae, Claude Code, Cursor, Windsurf, Gemini CLI, and Copilot; structured JSON output designed for both humans and agents
+- **Two-layer parameters** — ergonomic `--flag-name` for everyday use, with a `--params <json>` fallback for complex payloads
+- **Flexible output** — `json` / `table` / `ndjson` / `raw` formats, with `--select` dot-path projection for piping to other tools
+- **Non-interactive auth** — OAuth browser login plus a `--device-code` flow for CI and agent shells
+- **Dry-run previews** — `--dry-run` on mutation commands to inspect the exact payload before sending
+- **Secure by default** — OS keychain credential storage, `${VAR}` env-var templating so secrets stay out of config files, and multi-profile switching for staging / production

package/README.md

@@ -1,22 +1,63 @@
 # Meegle CLI
 
-> **DEV** — Currently in developer preview. APIs and commands may change.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D16-brightgreen.svg)](https://nodejs.org/)
+[![npm version](https://img.shields.io/npm/v/@lark-project/meegle.svg)](https://www.npmjs.com/package/@lark-project/meegle)
+
+[English](./README.md) | [简体中文](./README.zh-CN.md)
 
 Command-line tool for [Meegle](https://meegle.com?utm_source=github&utm_medium=readme&utm_campaign=meegle_cli) ([Lark Project](https://project.feishu.cn?utm_source=github&utm_medium=readme&utm_campaign=meegle_cli)). Manage work items, schedules, and data from your terminal — no browser needed.
 
+[Install](#installation) · [Quick Start](#quick-start-human-users) · [Agent Skill](#ai-agent-skill) · [Commands](#commands) · [Auth](#authentication) · [Config](#configuration) · [Security](#security--risk-warnings) · [Contributing](#contributing)
+
+## Why Meegle CLI?
+
+- **Agent-Native** — Ships a bundled [AI Agent Skill](#ai-agent-skill) that teaches Trae, Claude Code, Cursor, Windsurf, Gemini CLI and other agents how to drive Meegle with one command. Every CLI command is designed for both humans and agents, with structured JSON output, `--dry-run` previews, and `--device-code` flows for non-TTY environments
+- **Broad Coverage** — 12 business domains (work items, workflow, subtasks, comments, work hours, relations, my-work, views, charts, team, user, project) and 40+ commands mapping to Meegle's core capabilities
+- **Two-Layer Parameters** — Ergonomic `--flag-name` for everyday use, fallback `--params <json>` for complex payloads like `fields[]` — pick the right granularity per call
+- **Flexible Output** — `json` / `table` / `ndjson` / `raw`, with `--select` dot-path projection for piping to other tools
+- **Secure by Default** — OS keychain credential storage, `${VAR}` env-var templating so secrets never land in config files, multi-profile switching for staging / prod
+
+## Features
+
+| Category                                           | Capabilities                                                                                   |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 📋 [Work Items](#workitem--work-items)             | Create, read, update, batch-read, query (MQL), list operation records, inspect metadata        |
+| 🔀 [Workflow](#workflow--workflow)                 | Transition nodes & states, update node fields, list available transitions and required fields |
+| ✅ [Subtasks](#subtask--subtasks)                  | Create, update, complete, rollback subtasks                                                    |
+| 💬 [Comments](#comment--comments)                  | Add and list comments on work items                                                            |
+| ⏱️ [Work Hours](#workhour--work-hours)             | List work hour records, view team-member schedules                                             |
+| 🔗 [Relations](#relation--relations)               | List related work items, inspect relation-type definitions                                     |
+| 📌 [My Work](#mywork--my-work)                     | View this week / overdue / completed to-dos                                                    |
+| 👁️ [Views](#view--views)                           | Create and update fixed views, search views by name                                            |
+| 📊 [Charts](#chart--charts)                        | List charts under a view, fetch chart details                                                  |
+| 👥 [Team & User](#team--user--people)              | List teams, team members, search users, view current login                                     |
+| 🗂️ [Projects](#project--projects)                  | Search projects by keyword                                                                     |
+| 🔐 [Auth & Config](#authentication)                | OAuth login, device-code flow, multi-profile config, env-var injection                         |
+| 🔗 [URL Parsing](#url--url-parsing)                | Offline decode of Meegle / Feishu Project URLs into `url_kind` + structured fields             |
+| 🤖 [Agent Skill](#ai-agent-skill)                  | Pre-built skill for Trae / Claude Code / Cursor / Windsurf / Gemini CLI / Copilot              |
 
 ## Installation
 
+### Requirements
+
+- Node.js >= 16 (ships with `npm` / `npx`)
+
+### Install
+
 ```bash
 npm install -g @lark-project/meegle
 ```
 
-Requires Node.js >= 16.
+## Quick Start (Human Users)
 
-## Quick Start
+> **Note for AI assistants:** if you are an AI Agent helping the user set this up, jump directly to [Quick Start (AI Agent)](#quick-start-ai-agent--ci--headless) — it contains the non-interactive steps you need.
 
 ```bash
-# 1. Log in
+# (Optional) Persist the host so future logins skip the arrow-key picker
+meegle config set host <host>
+
+# 1. Log in (arrow-key host picker + browser OAuth)
 meegle auth login
 
 # 2. View this week's to-dos
@@ -30,27 +71,84 @@ meegle workitem --help
 meegle inspect workitem.create
 ```
 
-## Non-interactive setup (CI / agent shells / Claude Code)
+## Quick Start (AI Agent / CI / Headless)
 
-`meegle auth login` defaults to an arrow-key host picker plus the
-Authorization Code OAuth flow. Both require a real TTY and a local browser
-callback, so they will fail or hang in environments such as CI runners,
-pipes, or agent shells like Claude Code.
+The default `meegle auth login` uses an arrow-key host picker plus a browser OAuth callback — both require a real TTY, so they will hang or fail in CI runners, pipes, and agent shells like Claude Code. Use the Device Code flow instead: it prints an authorization URL that the user opens in any browser.
 
-In those environments use the Device Code flow instead — it prints a URL
-that the operator opens in any browser to grant access:
+**Step 1 — Install the CLI**
 
 ```bash
-# Option A: pass the host inline each time
-meegle auth login --device-code --host <host>
+npm install -g @lark-project/meegle
+```
 
-# Option B: persist the host once, then log in
+**Step 2 — Persist the host**
+
+```bash
 meegle config set host <host>
+```
+
+Examples of `<host>`: `project.feishu.cn`, `meegle.com`, or your self-hosted tenant domain such as `your-tenant.example.com`.
+
+**Step 3 — Log in with Device Code**
+
+> Run this command in the background. It prints an authorization URL — extract it and send it to the user. The command exits automatically once the user completes authorization in the browser.
+
+```bash
 meegle auth login --device-code
 ```
 
-Examples of `<host>`: `project.feishu.cn`, `meegle.com`, or your
-self-hosted tenant domain such as `your-tenant.example.com`.
+Alternatively, pass the host inline each time without persisting it:
+
+```bash
+meegle auth login --device-code --host <host>
+```
+
+**Step 4 — Verify**
+
+```bash
+meegle auth status
+```
+
+For fully unattended CI (no human-in-the-loop), inject a token via environment variables instead — see [Sandbox / CI](#sandbox--ci-direct-environment-variable-injection).
+
+## AI Agent Skill
+
+`skills/meegle/` is a drop-in **skill** that teaches AI Agents — Trae, Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot CLI — how to operate Meegle through this CLI. It bundles the command catalog, MQL syntax, field-value conventions, rich-text Markdown rules, and standard operating procedures for common write flows.
+
+### Install
+
+```bash
+# Install the CLI first (the skill calls `meegle` under the hood)
+npm install -g @lark-project/meegle
+
+# Then add the skill — auto-detects installed agents and registers in each
+npx skills add larksuite/meegle-cli -y -g
+```
+
+`npx skills add` reads `skills/meegle/SKILL.md` from the repo and drops it into the skill directory of every agent CLI it finds on the machine. Re-run any time to pick up updates.
+
+### What it covers
+
+- **Command reference** — every `meegle` resource / method with required parameters and examples
+- **MQL search** — syntax for `workitem query`, operators, scope keywords
+- **Field values** — how to shape complex field payloads (arrays, nested JSON, date ranges)
+- **Rich text** — Markdown subset supported by Meegle's rich-text editor
+- **SOPs** — step-by-step playbooks for creating work items, transitioning nodes, transitioning states, and updating fields
+- **Auth guard** — the skill refuses to run business commands until `meegle auth status` succeeds
+
+See [skills/meegle/SKILL.md](./skills/meegle/SKILL.md) and [skills/meegle/references/](./skills/meegle/references/) for the full contents.
+
+### Usage
+
+Once installed, just ask the agent in natural language. For example, in Trae:
+
+```
+Show me this week's P0 stories in the PROJ space.
+```
+
+The agent consults the skill, picks the right `meegle` commands, and runs them for you. Pair with `--dry-run` (see [Security](#security--risk-warnings)) to preview side-effectful operations before the agent commits them.
+
+> Heads up: the skill name `meegle` is the same string as the CLI binary. When documentation refers to "the **`meegle` skill**" it means the files in `skills/meegle/`; when it refers to "the **`meegle` CLI**" it means the `meegle` command on your PATH.
 
 ## Commands
 
@@ -60,6 +158,7 @@ self-hosted tenant domain such as `your-tenant.example.com`.
 |---------|-------------|
 | `workitem create` | Create a work item |
 | `workitem get` | View work item details |
+| `workitem +batch-get` | Batch-read work items by IDs (client-side fan-out over `workitem get`; `+` marks scenario/sugar commands) |
 | `workitem update` | Update work item fields |
 | `workitem query` | Search work items using MQL |
 | `workitem list-op-records` | View operation records |
@@ -144,6 +243,15 @@ self-hosted tenant domain such as `your-tenant.example.com`.
 |---------|-------------|
 | `project search` | Search projects |
 
+### attachment — Attachments
+
+| Command | Description |
+|---------|-------------|
+| `attachment prepare-upload` | Upload preprocess — returns the signed object-storage URL and multipart plan |
+| `attachment prepare-download` | Download preprocess — returns the signed object-storage URL and multipart plan |
+| `attachment +upload` | End-to-end upload: preprocess + signed HTTP POST(s); returns the resulting `file_token` and file metadata |
+| `attachment +download` | End-to-end download: preprocess + signed HTTP GET(s) + atomic write — for `file_url`s embedded in `workitem get` / `comment list` responses |
+
 ### auth — Authentication
 
 | Command | Description |
@@ -162,6 +270,14 @@ self-hosted tenant domain such as `your-tenant.example.com`.
 | `config get` | Get a configuration value |
 | `config profile create\|list\|use\|current\|delete` | Manage configuration profiles |
 
+### url — URL Parsing
+
+Offline, no-network utility for parsing Meegle / Feishu Project URLs into structured fields. Skills and pipelines branch on the returned `url_kind` instead of guessing from raw paths.
+
+| Command | Description |
+|---------|-------------|
+| `url decode --url <URL>` | Decode a URL into `url_kind` + `simple_name` / `work_item_type` / `work_item_id` / `view_id` / `chart_id` / `query` / `redirected_from` etc. Unrecognised URLs return `url_kind: "unknown"`. |
+
 ### Other Commands
 
 | Command | Description |
@@ -195,18 +311,58 @@ meegle workitem get --work-item-id 12345
 meegle workflow get-node --work-item-id 12345 --need-sub-task
 ```
 
+### Batch Reading Work Items
+
+`workitem +batch-get` fans out to `workitem get` for each ID and aggregates the
+results into one response. Shared flags (e.g. `--project-key`) apply to every
+per-item call. The `+` prefix marks it as a scenario/sugar command — the CLI
+composes multiple `get` calls client-side instead of mapping to a single
+backend endpoint.
+
+```bash
+# Comma-separated IDs in one invocation
+meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346,12347"
+
+# Read IDs from a file (one per line; lines starting with '#' are comments)
+meegle workitem +batch-get --project-key PROJ --ids-file ./ids.txt
+
+# Stream one JSON row per item; summary row is emitted last
+meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346" -o ndjson
+```
+
+Response envelope (JSON):
+
+```json
+{
+  "summary": { "total": 3, "succeeded": 2, "failed": 1 },
+  "results": [
+    { "work_item_id": 12345, "data": { /* ... */ } },
+    { "work_item_id": 12346, "data": { /* ... */ } },
+    { "work_item_id": 12347, "error": { "code": "...", "message": "..." } }
+  ]
+}
+```
+
+Constraints: up to 200 IDs per invocation, 3 concurrent workers (fixed).
+Partial failures do **not** abort the batch — check `summary.failed` or the
+per-item `error` field. A 401 from the server aborts the whole run.
+
 ### Creating Work Items
 
 ```bash
-# Use --set to set fields
+# Pass fields[] via --params (JSON)
 meegle workitem create --project-key PROJ --work-item-type story \
-  --set name="Optimize login flow" \
-  --set priority=P1
+  --params '{"fields":[
+    {"field_key":"name","field_value":"Optimize login flow"},
+    {"field_key":"priority","field_value":"P1"}
+  ]}'
 
-# Pass JSON values for complex fields
+# Complex field values (arrays, nested JSON) also go through --params
 meegle workitem create --project-key PROJ --work-item-type story \
-  --set name="Scheduled task" \
-  --set schedule='[1722182400000,1722355199999]'
+  --params '{"fields":[
+    {"field_key":"name","field_value":"Scheduled task"},
+    {"field_key":"schedule","field_value":[1722182400000,1722355199999]}
+  ]}'
 ```
 
 ### Updating Fields
@@ -214,14 +370,112 @@ meegle workitem create --project-key PROJ --work-item-type story \
 ```bash
 # Update work item name
 meegle workitem update --work-item-id 12345 \
-  --set name="New title"
+  --params '{"fields":[{"field_key":"name","field_value":"New title"}]}'
 
 # Update multiple fields at once
 meegle workitem update --work-item-id 12345 \
-  --set name="New title" \
-  --set priority=P0
+  --params '{"fields":[
+    {"field_key":"name","field_value":"New title"},
+    {"field_key":"priority","field_value":"P0"}
+  ]}'
+```
+
+### Attachments
+
+The `attachment` domain exposes Lark project's two-stage attachment protocol
+in two layers:
+
+- **Basic commands** (`attachment prepare-upload`, `attachment prepare-download`)
+  return the raw signed-URL preprocess payload — handy for scripting your own
+  HTTP transfer or inspecting the multipart plan.
+- **Shortcuts** (`attachment +upload`, `attachment +download`) chain the basic
+  preprocess with the signed HTTP POST/GET to object storage end-to-end. The
+  `+` prefix marks them as scenario commands — the CLI orchestrates the
+  preprocess output plus the out-of-band byte transfer client-side.
+
+`--resource-type` tells the backend what the file will be attached to:
+
+| `--resource-type` | Target |
+|-------------------|--------|
+| `15` | Workitem attachment field |
+| `16` | Image embedded in a workitem rich-text field |
+| `13` | Attachment on a comment |
+| `14` | Image embedded in a comment |
+
+**Scoping the preprocess**: every upload needs either `--work-item-id` or
+`--work-item-type`. **Always prefer `--work-item-id`** when the target workitem
+exists (update / comment scenarios); only use `--work-item-type` for the
+create-with-attachment path where the workitem hasn't been created yet. If
+both are supplied, `--work-item-id` wins and `--work-item-type` is ignored.
+
+```bash
+# Upload a file for a workitem attachment field (resource-type 15)
+meegle attachment +upload ./a.pdf \
+  --resource-type 15 \
+  --project-key PROJ --work-item-id 12345 --field-key files_field
+
+# Create-with-attachment path — workitem doesn't exist yet, pass --work-item-type
+meegle attachment +upload ./a.pdf \
+  --resource-type 15 \
+  --project-key PROJ --work-item-type story --field-key files_field
+
+# Upload an image for a rich-text field (resource-type 16)
+meegle attachment +upload ./diagram.png \
+  --resource-type 16 \
+  --project-key PROJ --work-item-id 12345 --field-key spec_field
+
+# Upload a comment attachment (resource-type 13)
+meegle attachment +upload ./report.pdf \
+  --resource-type 13 \
+  --project-key PROJ --work-item-id 12345
+
+# Upload a comment image (resource-type 14)
+meegle attachment +upload ./screen.png \
+  --resource-type 14 \
+  --project-key PROJ --work-item-id 12345
+
+# Download: pass the opaque file_url from another command's response.
+URL=$(meegle workitem get --project-key PROJ --work-item-id 12345 \
+        --fields files_field --format json \
+      | jq -r '.fields.files_field[0].url')
+meegle attachment +download "$URL" \
+  --project-key PROJ --work-item-id 12345 \
+  --output ./local.pdf --overwrite
+```
+
+`+upload` returns a JSON object with the file token and metadata:
+
+```json
+{
+  "file_token": "...",
+  "file_url": "https://...",
+  "name": "a.pdf",
+  "size": 12345,
+  "mime_type": "application/pdf"
+}
+```
+
+To wire the result into a downstream command, parse the response with `jq`
+or your scripting language of choice:
+
+```bash
+# Comment attachment — comment add takes file_token directly
+TOKEN=$(meegle attachment +upload ./report.pdf --resource-type 13 \
+        --project-key PROJ --work-item-id 12345 | jq -r '.file_token')
+meegle comment add --work-item-id 12345 --content "See attached" --file-token "$TOKEN"
 ```
 
+**Field-level attachment formats** (how to assemble `--fields` payloads):
+
+- **Workitem attachment field** (`--resource-type 15`) — `field_value` is a
+  JSON *string* whose parsed form is `[{"name","type","size","fileToken"}]`.
+  Note: `fileToken` is camelCase (other backend fields are snake_case) and
+  `size` is a string, not a number.
+- **Rich-text field / comment image** (`--resource-type 16` / `14`) — embed
+  images as `![name](file_url) <!-- file_token -->`.
+- **Comment attachment** (`--resource-type 13`) — `comment add --file-token`
+  takes `file_token` directly.
+
 ### MQL Search
 
 ```bash
@@ -255,19 +509,31 @@ Each command takes parameters via `--flag-name`:
 meegle workitem get --work-item-id 12345 --project-key PROJ
 ```
 
-### --set key=value (Write Commands)
+### Writing `fields[]` (Write Commands)
+
+`workitem create`, `workitem update`, `workflow update-node`, and `subtask update` expect the `fields[]` payload. Pass it through `--params`:
+
+```bash
+--params '{"fields":[
+  {"field_key":"name","field_value":"Title"},
+  {"field_key":"priority","field_value":"P1"}
+]}'
+```
+
+### --set key=value (Generic)
 
-`workitem create`, `workitem update`, `workflow update-node`, and `subtask update` support `--set` for convenient field assignment:
+`--set` is an alternate syntax for writing **top-level** parameters — `--set key=value` is equivalent to typing `--key value`. Useful when scripting with a uniform `key=value` form, or for writing nested top-level params via dot-path. Values are auto-typed (int / float / bool / string).
 
 ```bash
---set name="Title"              # String
---set points=5                  # Number
---set is_urgent=true            # Boolean
---set schedule='[1,2]'          # JSON array
---set role='{"role":"RD"}'      # JSON object
+# These two are equivalent:
+meegle mywork todo --action this_week --page-num 1
+meegle mywork todo --set action=this_week --set page_num=1
+
+# Dot-path builds nested maps (rarely used in Meegle, but supported):
+--set extra.flag=true          # becomes {"extra":{"flag":true}}
 ```
 
-`--set` can be repeated to set multiple fields at once.
+`--set` only writes **top-level** parameters. To write a work item's `fields[]`, use `--params '{"fields":[...]}'` (see below).
 
 ### --params JSON (Fallback)
 
@@ -278,12 +544,37 @@ meegle workitem create --project-key PROJ --work-item-type story \
   --params '{"fields":[{"field_key":"name","field_value":"Title"}]}'
 ```
 
+#### Reading from a file (`@file.json`)
+
+Inline JSON is unergonomic on Windows because CMD requires `\"` escaping
+and PowerShell mangles backslashes when forwarding native-command arguments.
+Prefix the value with `@` to load the JSON from a file instead — works
+identically on macOS, Linux, and Windows shells:
+
+```bash
+# body.json:
+# {"fields":[{"field_key":"name","field_value":"Optimize login flow"}]}
+
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params @body.json
+
+# Absolute path also works
+meegle workitem update --work-item-id 12345 --params @/tmp/patch.json
+
+# PowerShell — same syntax, no escaping headaches
+meegle workitem create --project-key PROJ --work-item-type story --params '@body.json'
+```
+
+The path is read with the OS's default encoding; both relative and absolute
+paths are accepted. A missing file fails with `PARAM_INVALID`; a file whose
+contents are not valid JSON fails with `INVALID_PARAMS_JSON`.
+
 ### Priority
 
 When `--set`, `--params`, and regular flags are used together:
 
-1. `--set` overrides fields with the same name in `--params`
-2. Regular flags (e.g. `--project-key`) override top-level keys in `--params`
+1. Regular CLI flags beat `--params` / `--set` for the same top-level key
+2. `--set` overrides the same top-level key from `--params`
 
 ### Array Parameters
 
@@ -306,55 +597,80 @@ meegle workflow get-node --work-item-id 12345 --need-sub-task
 
 | Flag | Short | Description |
 |------|-------|-------------|
-| `--format` | `-o` | Output format: `json` (default), `table`, `ndjson`, `yaml`, `markdown`, `raw` |
+| `--format` | `-o` | Output format: `json` (default), `table`, `ndjson`, `raw` |
 | `--select` | | Field projection with dot paths |
 | `--set` | | Set nested parameters (repeatable) |
-| `--params` | `-P` | Full JSON parameter body |
+| `--params` | `-P` | Full JSON parameter body; prefix with `@` to read from a file (e.g. `--params @body.json`) |
 | `--dry-run` | | Render request without executing |
 | `--verbose` | `-v` | Verbose output |
 | `--profile` | | Use a specific configuration profile |
+| `--refresh` | | Refresh cached commands from server (bypass the local 24 h cache) |
 
-## Output Formats
+## Advanced Usage
+
+### Output Formats
 
 ```bash
 # JSON (default)
 meegle workitem get --work-item-id 12345
 
-# Select output properties (supports dot paths)
-meegle workitem get --work-item-id 12345 --select "id,name,status"
-meegle mywork todo --action done --page-num 1 --select "list.work_item_info.work_item_name"
-
 # NDJSON (suitable for piping)
 meegle mywork todo --action this_week --page-num 1 -o ndjson
 
 # Table
 meegle mywork todo --action this_week --page-num 1 -o table
+```
+
+### Field Projection with `--select`
+
+`--select` projects fields using `.` notation. A segment after an array
+broadcasts the remaining path over every record of the array and
+collects the results while preserving the enclosing structure.
 
-# YAML
-meegle workitem get --work-item-id 12345 -o yaml
+| Expression | Response | Projection |
+|---|---|---|
+| `list` | `{"list":[{"a":1}], "total":1}` | `{"list":[{"a":1}]}` |
+| `list.a` | `{"list":[{"a":1,"b":2},{"a":3,"b":4}]}` | `{"list":[{"a":1},{"a":3}]}` |
+| `list.a,list.b` | same as above | `{"list":[{"a":1,"b":2},{"a":3,"b":4}]}` (merged per index) |
+| `list.work_item_info.work_item_name` | `{"list":[{"work_item_info":{"work_item_name":"x"}}]}` | `{"list":[{"work_item_info":{"work_item_name":"x"}}]}` |
+| `nodes.0` | `{"nodes":[{"id":"a"},{"id":"b"}]}` | `{"nodes":{"0":{"id":"a"}}}` (numeric = index) |
 
-# Markdown table
-meegle mywork todo --action this_week --page-num 1 -o markdown
+```bash
+# Top-level selection
+meegle workitem get --work-item-id 12345 --select "id,name,status"
 
-# Dry run (preview request without sending)
-meegle workitem create --project-key PROJ --work-item-type story --set name="Test" --dry-run
+# Broadcast across arrays — extract fields from nested records
+meegle mywork todo --action done --page-num 1 \
+  --select "list.work_item_info.work_item_name,list.state_info.end_state_key_name"
+
+# Mix top-level metadata with broadcast — total is retained alongside projected list items
+meegle mywork todo --action done --page-num 1 \
+  --select "total,list.work_item_info.work_item_name"
 ```
 
-### --select Dot Paths
+### Metadata preservation
 
-`--select` supports `.` notation for nested properties, automatically traversing arrays:
+The default render preserves the full response shape across every
+`--format`: list endpoints return `{"list":[...], "total":N,
+"pagination":{...}}` verbatim — you see `total` / `pagination` even
+when you do not project them. Drill into records explicitly via
+`--select` (and the broadcast syntax above). Under `--format table`
+and `--format ndjson`, a single-key wrapper like `{"list":[...]}`
+(no sibling metadata) is still peeled into rows — the peel is
+loss-less.
 
-```bash
-# Extract fields from nested structures
---select "list.work_item_info.work_item_name,list.state_info.end_state_key_name"
+### Dry Run
 
-# Mix top-level and nested
---select "total,list.work_item_info.work_item_name"
+For commands with side effects, preview the rendered request with `--dry-run` before executing:
+
+```bash
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params '{"fields":[{"field_key":"name","field_value":"Test"}]}' --dry-run
 ```
 
-## Command Introspection
+### Command Introspection
 
-Use `inspect` to view full parameter information for a command:
+Use `inspect` to view full parameter information for any command:
 
 ```bash
 # List all commands
@@ -419,6 +735,7 @@ Main config options:
 | `host` | Site domain | `project.feishu.cn`, `meegle.com` |
 | `user_access_token` | User access token; use `${VAR}` to read from an environment variable | `${CI_MEEGLE_TOKEN}` |
 | `access_token_header` | Custom HTTP header name that carries the token; empty falls back to default `Authorization: Bearer <token>` | `x-meegle-auth` |
+| `user_agent` | Caller suffix appended to the default `User-Agent` (form: `meegle-cli/<ver> <user_agent>`); supports `${VAR}` template; overridden by the `MEEGLE_USER_AGENT` env var | `my-service/1.0` |
 
 ### Sandbox / CI: Direct Environment-Variable Injection
 
@@ -427,7 +744,8 @@ Two well-known environment variables are read directly at CLI startup and overri
 ```bash
 export MEEGLE_HOST=project.feishu.cn
 export MEEGLE_USER_ACCESS_TOKEN=<your-user-token>
-meegle workitem get-brief --work_item_id 123
+export MEEGLE_USER_AGENT=ci-runner  # optional; appended to User-Agent, highest priority over config.user_agent
+meegle workitem get --work-item-id 123
 ```
 
 Either variable may be set independently. When this path is taken, the CLI bypasses the keychain and does not attempt to refresh on 401 — the caller is responsible for rotating the env value.
@@ -503,6 +821,26 @@ meegle auth login
 
 The command list is cached automatically and refreshed silently in the background when expired.
 
+## Security & Risk Warnings
+
+This tool is designed to be called by AI Agents to automate Meegle operations, which carries inherent risks — model hallucinations, unpredictable execution, and prompt injection. Once you authorize Meegle permissions, the Agent will act under your user identity within the granted scope, and may perform high-impact actions (field updates, status transitions, work item creation) on your behalf. Use with care.
+
+Recommended safeguards:
+
+- Preview side-effectful commands with `--dry-run` before running them
+- Use a dedicated profile (`meegle config profile create`) for Agent-driven sessions so you can audit and revoke independently
+- For CI / shared environments, prefer short-lived env-var token injection (`MEEGLE_USER_ACCESS_TOKEN`) and rotate on 401 — do not relax default security settings
+
+By using this tool you are deemed to voluntarily assume all related responsibilities.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=larksuite/meegle-cli&type=Date)](https://star-history.com/#larksuite/meegle-cli&Date)
+
+## Contributing
+
+Community contributions are welcome. For bugs and feature requests, open an [Issue](https://github.com/larksuite/meegle-cli/issues) or [Pull Request](https://github.com/larksuite/meegle-cli/pulls). For major changes, please start a discussion via an Issue first.
+
 ## License
 
 This project is licensed under the **MIT License**.