@newpeak/barista-cli 0.1.15 → 0.1.16

package/README.md

@@ -1,630 +1,268 @@
 # ☕ Barista CLI
 
-<p align="center">
-  <a href="https://gitlab.newpeaksh.com/coffee/coffee-barista-cli/blob/develop/README.md"><img src="https://img.shields.io/badge/-简体中文-green?style=flat-square" alt="简体中文"></a>
-  <a href="https://gitlab.newpeaksh.com/coffee/coffee-barista-cli/blob/develop/README.en.md"><img src="https://img.shields.io/badge/-English-blue?style=flat-square" alt="English"></a>
-  <a href="https://gitlab.newpeaksh.com/coffee/coffee-barista-cli/blob/develop/README.ja.md"><img src="https://img.shields.io/badge/-日本語-red?style=flat-square" alt="日本語"></a>
-  <a href="https://gitlab.newpeaksh.com/coffee/coffee-barista-cli/blob/develop/README.vi.md"><img src="https://img.shields.io/badge/-Tiếng%20Việt-green?style=flat-square" alt="Tiếng Việt"></a>
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/AI--Native-CLI-blue?style=flat-square" alt="AI-Native">
-  <img src="https://img.shields.io/badge/Liberica-Production%20SaaS-green?style=flat-square" alt="Liberica">
-  <img src="https://img.shields.io/badge/Arabica-在线订阅%20SaaS-orange?style=flat-square" alt="Arabica">
-  <img src="https://img.shields.io/badge/Node.js-18%2B-brightgreen?style=flat-square" alt="Node.js 18+">
-</p>
-
-<p align="center">
-  <strong>AI-Native CLI 工具</strong>，无缝桥接 Liberica 生产管理 SaaS 与 Arabica 在线订阅 SaaS 服务
-</p>
+> **Let AI assistants control production management systems** — Bridge AI tools (Claude Code, OpenCode, OpenClaw) to enterprise SaaS
 
----
-
-## 📋 目录
-
-- [项目简介](#项目简介)
-- [快速开始](#快速开始)
-- [架构设计](#架构设计)
-- [命令文档](#命令文档)
-- [高级特性](#高级特性)
-- [配置说明](#配置说明)
-- [AI 集成](#AI-集成)
-- [开发指南](#开发指南)
-- [贡献指南](#贡献指南)
+[![npm version](https://img.shields.io/npm/v/@newpeak/barista-cli.svg?style=flat-square)](https://www.npmjs.com/package/@newpeak/barista-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
+[![Weekly Downloads](https://img.shields.io/npm/dw/@newpeak/barista-cli?style=flat-square)](https://www.npmjs.com/package/@newpeak/barista-cli)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen?style=flat-square)](https://nodejs.org/)
 
 ---
 
-## 项目简介
-
-Barista CLI 是专为 Newpeak 生态系统设计的 AI-Native 命令行工具。它提供统一的接口来管理 Liberica 生产管理 SaaS 和 Arabica 在线订阅 SaaS 服务。
+## ⚡ Quick Start
 
-### 核心特性
-
-| 特性 | 说明 |
-|------|------|
-| 🌍 **多环境支持** | dev、test、prod-cn、prod-jp 四环境无缝切换 |
-| 🏢 **多租户架构** | 支持多租户环境配置与隔离 |
-| 🔐 **Token 认证** | 安全存储于系统密钥链，环境隔离 |
-| 🧪 **Dry-Run 模式** | 所有写入操作支持预览，避免误操作 |
-| 🤖 **AI 集成** | 为 Claude Code 优化的 JSON 输出格式 |
-| 🔄 **跨服务操作** | Liberica 与 Arabica 之间的数据同步 |
-
-### 适用场景
-
-- **生产计划管理**：创建、查询、取消生产订单
-- **产品数据管理**：跨平台搜索、同步产品信息
-- **客户操作**：查询客户信息、生成报价单
-- **AI 自动化**：通过 Claude Code 实现业务流程自动化
-
----
-
-## 快速开始
-
-### 安装
+### 1. Install
 
 ```bash
-# 通过 npm 安装
 npm install -g @newpeak/barista-cli
-
-# 或通过 yarn
-yarn global add @newpeak/barista-cli
-
-# 验证安装
-barista --version
 ```
 
-### 初始化配置
+### 2. Authenticate
 
 ```bash
-# 1. 初始化配置目录
-barista init
-
-# 2. 使用凭证登录（推荐方式，自动设置环境和租户）
-barista liberica auth login dev your-tenant your-username your-password
+# AI needs credentials to operate on behalf of user
+barista liberica auth login prod-cn your-tenant your-username your-password
 
-# 或交互式登录（系统会提示输入缺失信息）
+# Interactive login (prompts for missing info)
 barista liberica auth login
-
-# 3. 验证登录状态
-barista auth status
-
-# 4. 查看当前上下文（确认环境已自动设置）
-barista context show
 ```
 
-**注意**：使用 `barista liberica auth login` 登录后，系统会自动设置当前环境上下文，后续命令无需指定 `--env` 和 `--tenant` 参数。
-
-### 基本使用示例
-
-```bash
-# 查看当前上下文
-barista context show
-
-# 列出所有订单（Liberica）
-barista liberica orders list
-
-# 搜索产品（支持模糊查询）
-barista liberica products search --keyword "咖啡机"
-
-# 查看 Arabica 产品目录
-barista arabica products public-catalog
-
-# 创建生产订单（dry-run 模式预览）
-barista liberica orders create --product-id 123 --quantity 100 --dry-run
-```
-
----
-
-## 架构设计
+### 3. AI Integration
 
-### 环境映射
-
-#### Liberica（生产管理 SaaS）
-
-| 环境 | 域名格式 | 说明 |
-|------|----------|------|
-| dev | `{tenant}-dev.newpeaksh.com` | 开发环境 |
-| test | `{tenant}-test.newpeaksh.com` | 测试环境 |
-| prod-cn | `{tenant}.newpeaksh.com` | 中国生产环境 |
-| prod-jp | `{tenant}.newpeakjp.com` | 日本生产环境 |
-
-#### Arabica（在线订阅 SaaS 服务）
-
-| 环境 | 域名 | 说明 |
-|------|------|------|
-| dev | `arabica-dev.newpeaksh.com` | 开发环境 |
-| test | `arabica-test.newpeaksh.com` | 测试环境 |
-| prod-cn | `www.newpeaksh.com` | 中国生产环境 |
-| prod-jp | `members.newpeakjp.com` | 日本生产环境 |
-
-### 认证机制
-
-Barista CLI 采用 Token-based 认证机制：
+```typescript
+// In Claude Code / OpenCode / OpenClaw:
+const orders = await $`barista liberica orders list --env prod-cn --tenant your-tenant --json`
+const { success, data } = JSON.parse(orders.stdout)
 
+// AI parses and acts on the data
+if (data.items.length > 0) {
+  console.log(`Found ${data.pagination.total} orders`)
+}
 ```
-┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
-│   Barista CLI   │────▶│   Auth Server    │────▶│   API Servers   │
-│                 │     │                  │     │                 │
-│ • 登录请求      │     │ • 验证凭证       │     │ • 验证 Token    │
-│ • 存储 Token    │◀────│ • 签发 JWT       │◀────│ • 返回数据      │
-│   (系统密钥链)  │     │                  │     │                 │
-└─────────────────┘     └──────────────────┘     └─────────────────┘
-```
-
-**安全特性：**
 
-- **密钥链存储**：Token 安全存储于系统密钥链（macOS Keychain、Windows Credential、Linux Secret Service）
-- **自动跳过认证**：公开接口（如产品目录查询）无需认证
-- **环境隔离**：每个环境和租户使用独立的 Token，互不影响
-- **Token 刷新**：支持自动刷新即将过期的 Token
+**[View AI Integration Examples →](#ai-integration)**
 
 ---
 
-## 命令文档
-
-> **完整命令清单**: 所有命令的完整参考（包括已实现和待开发状态）请查看 [命令参考](./docs/commands/REFERENCE.md)。
-
-### 命令结构
-
-```
-barista <service> <resource> <action> [options]
-```
-
-**示例：**
-
-```bash
-barista liberica orders list --page 1 --size 20
-barista arabica quotes calculate --product-id 123 --quantity 10
-```
-
-### 全局选项
+## 🤖 AI Integration
 
-| 选项 | 说明 | 示例 |
-|------|------|------|
-| `--env` | 指定环境 | `--env prod-cn` |
-| `--tenant` | 指定租户 | `--tenant electionjp` |
-| `--service` | 指定服务 | `--service liberica` |
-| `--dry-run` | 预览模式 | `--dry-run` |
-| `--json` | JSON 输出 | `--json` |
-| `--help` | 显示帮助 | `--help` |
+Barista CLI is designed for AI coding assistants. Every output is structured, every error is actionable.
 
-### 上下文管理
+### Supported AI Tools
 
-上下文管理用于快速切换工作环境，避免每个命令都指定环境参数。
+| AI Tool | Integration Method | Status |
+|---------|-------------------|--------|
+| **Claude Code** | `$` backticks + `--json` | ✅ Verified |
+| **OpenCode** | Shell command + JSON parse | ✅ Verified |
+| **OpenClaw** | Shell command + JSON parse | ✅ Verified |
+| **Cursor** | Terminal integration | ✅ Compatible |
+| **Continue** | CLI subprocess | ✅ Compatible |
 
-```bash
-# 查看当前上下文
-barista context show
-
-# 输出示例：
-# ┌─────────────┬─────────────────┐
-# │ 属性        │ 值              │
-# ├─────────────┼─────────────────┤
-# │ 当前环境    │ dev             │
-# │ 当前租户    │ electionjp      │
-# │ 当前服务    │ liberica        │
-# │ Token 状态  │ 已登录          │
-# │ Token 过期  │ 2024-12-31      │
-# └─────────────┴─────────────────┘
-
-# 切换环境
-barista context use-env [dev|test|prod-cn|prod-jp]
-
-# 切换租户
-barista context use-tenant <tenant-name>
-
-# 切换默认服务
-barista context use-service [liberica|arabica]
-```
-
-### 认证管理
-
-Barista CLI 提供两种登录方式：
-
-#### 1. 凭证登录（推荐）
-使用用户名和密码进行完整认证流程，自动获取并存储 Token：
-
-```bash
-# Liberica 凭证登录
-barista liberica auth login <env> [tenant] [username] [password]
+### Integration Pattern
 
-# 示例：登录 Liberica 测试环境
-barista liberica auth login test electionjp admin@shanghai.newpeaksh.com 123456
-
-# 交互式登录（系统会提示输入缺失信息）
-barista liberica auth login
-
-# 登录后会自动设置当前环境上下文，后续命令无需指定 --env
-```
-
-#### 2. Token 直接存储
-适用于已有 JWT Token 的场景（如从其他渠道获取）：
-
-```bash
-# 直接存储 Token
-barista auth login --service <service> --env <env> [--tenant <tenant>]
-
-# 示例：存储 Liberica 开发环境 Token
-barista auth login --service liberica --env dev --tenant electionjp
-# 提示: Enter your token: [输入已有 Token]
-
-# 检查登录状态
-barista auth status
-
-# 输出示例：
-# ✓ Liberica (dev) - 已登录 (过期: 2024-12-31)
-# ✗ Liberica (test) - 未登录
-# ✓ Arabica (prod-cn) - 已登录 (过期: 2024-12-30)
-
-# 登出（清除 Token）
-barista auth logout --service <service> --env <env>
-
-# 登出所有环境
-barista auth logout --all
-```
-
-**重要**：使用 `barista liberica auth login` 登录后，系统会自动设置当前环境上下文，后续命令无需指定 `--env` 参数。
-
-### Liberica 命令
-
-#### 订单管理
-
-```bash
-# 列出订单（分页）
-barista liberica orders list [--page <n>] [--size <n>] [--status <status>]
-
-# 获取单个订单详情
-barista liberica orders get <order-id>
-
-# 创建订单
-barista liberica orders create \
-  --product-id <id> \
-  --quantity <n> \
-  [--delivery-date <date>] \
-  [--note <text>]
-
-# 取消订单
-barista liberica orders cancel <order-id> [--reason <text>]
-```
-
-#### 产品管理
+```typescript
+// 1. Execute command with JSON output
+const result = await $`barista liberica orders list \
+  --env prod-cn \
+  --tenant your-tenant \
+  --status pending \
+  --json \
+  --page 1 \
+  --size 50`
+
+// 2. Parse structured response
+const { success, data, meta } = JSON.parse(result.stdout)
+
+if (!success) {
+  throw new Error(`API Error: ${meta.code || meta.error?.code} - ${meta.message || meta.error?.message}`)
+}
 
-```bash
-# 搜索产品
-barista liberica products search --keyword <keyword> [--category <id>]
+// 3. Work with data
+const pendingOrders = data.items
+console.log(`Found ${data.pagination.total} pending orders`)
 
-# 获取产品详情
-barista liberica products get <product-id>
+// 4. Execute operations safely
+for (const order of pendingOrders) {
+  // Always dry-run first (AI safety)
+  const preview = await $`barista liberica orders cancel ${order.id} --dry-run`
 
-# 获取公开产品列表（无需认证）
-barista liberica products public-list [--category <id>] [--page <n>]
+  // Parse preview, verify, then execute with --force
+  // ...
+}
 ```
 
-#### 生产计划
-
-```bash
-# 查看生产排期
-barista liberica production schedule [--start-date <date>] [--end-date <date>]
+### Response Envelope
 
-# 重新排产
-barista liberica production reschedule <order-id> --new-date <date> [--dry-run]
+All JSON responses follow this structure:
 
-# 查询产能
-barista liberica production capacity [--date <date>] [--line <line-id>]
-```
-
-#### 仓库管理
-
-```bash
-# 列出仓库（分页）
-barista liberica warehouses list [--page <n>] [--size <n>] [--status <status>] [--name <name>] [--code <code>]
-
-# 获取仓库详情
-barista liberica warehouses get <warehouse-id>
-
-# 创建仓库
-barista liberica warehouses create --code <code> --name <name> \
-  [--type <type>] [--classes <classes>] [--address <address>] \
-  [--contact <contact>] [--phone <phone>] [--manager <manager>] \
-  [--enable-location] [--enable-negative-inventory] [--remark <remark>]
-
-# 更新仓库
-barista liberica warehouses update <warehouse-id> \
-  [--name <name>] [--type <type>] [--classes <classes>] [--address <address>] \
-  [--contact <contact>] [--phone <phone>] [--manager <manager>] \
-  [--enable-location] [--disable-location] \
-  [--enable-negative-inventory] [--disable-negative-inventory] \
-  [--remark <remark>]
-
-# 删除仓库（默认 Dry-Run，需 --force 确认）
-barista liberica warehouses delete <warehouse-id> [--force]
-
-# 启用仓库
-barista liberica warehouses enable <warehouse-id> [--force] [--dry-run]
-
-# 禁用仓库
-barista liberica warehouses disable <warehouse-id> [--force] [--dry-run]
+```json
+{
+  "success": true,
+  "data": {
+    "items": [...],
+    "pagination": { "page": 1, "size": 20, "total": 150 }
+  },
+  "meta": {
+    "requestId": "req-abc123",
+    "timestamp": "2024-01-15T10:30:00Z",
+    "environment": "prod-cn",
+    "tenant": "your-tenant"
+  }
+}
 ```
 
-#### 库位管理
-
-```bash
-# 列出库位（分页）
-barista liberica warehouses locations list --warehouse-id <id> \
-  [--page <n>] [--size <n>] [--status <status>] [--name <name>] [--code <code>]
-
-# 获取库位详情
-barista liberica warehouses locations get <location-id>
+**Error format:**
 
-# 创建库位
-barista liberica warehouses locations create --warehouse-id <id> --code <code> --name <name> \
-  [--type <type>] [--capacity <capacity>] [--remark <remark>] [--status <status>]
-
-# 更新库位
-barista liberica warehouses locations update <location-id> \
-  [--name <name>] [--type <type>] [--capacity <capacity>] [--remark <remark>] [--status <status>]
-
-# 删除库位（默认 Dry-Run，需 --force 确认）
-barista liberica warehouses locations delete <location-id> [--force]
-
-# 启用库位
-barista liberica warehouses locations enable <location-id> [--force] [--dry-run]
-
-# 禁用库位
-barista liberica warehouses locations disable <location-id> [--force] [--dry-run]
+```json
+{
+  "success": false,
+  "error": {
+    "code": "A150001",
+    "message": "Order not found"
+  },
+  "meta": {
+    "requestId": "req-xyz789",
+    "timestamp": "2024-01-15T10:30:00Z"
+  }
+}
 ```
 
-### Arabica 命令（订阅管理 SaaS）
-
-> Arabica 命令实现完整的 SaaS 订阅流程管理，包括套餐浏览、订阅管理、订单处理、发票查看等。
-
-#### 认证管理
-
-```bash
-# 登录 Arabica
-barista arabica auth login <account> <password>
-
-# 注册新会员
-barista arabica auth register --email <email> --account <account> --password <password>
-
-# 查看登录状态
-barista arabica auth status
-
-# 登出
-barista arabica auth logout
-```
+### Skills for Claude Code
 
-#### 套餐浏览
+Install reusable skill files:
 
 ```bash
-# 浏览可用套餐
-barista arabica plans list
-
-# 查看套餐详情
-barista arabica plans get <plan-id>
-
-# 对比两个套餐
-barista arabica plans compare <plan-a> <plan-b>
+# Skills are located at ~/.barista/claude/skills/
+barista skills install
 ```
 
-#### 订阅管理
-
-```bash
-# 查看当前订阅
-barista arabica subscription current
+**Available skills:**
+- `orders.md` — Order management workflow
+- `products.md` — Product search and sync
+- `warehouses.md` — Inventory operations
+- `subscriptions.md` — Arabica subscription management
 
-# 升级订阅
-barista arabica subscription upgrade <plan-id> [--seats <n>]
-
-# 降级订阅
-barista arabica subscription downgrade <plan-id>
-
-# 取消订阅
-barista arabica subscription cancel [--confirm]
-```
-
-#### 订单管理
+---
 
-```bash
-# 查看订单列表
-barista arabica orders list [--status pending|paid|cancelled|refunded]
+## 🚀 Features
 
-# 查看订单详情
-barista arabica orders get <order-id>
+### AI-First Design
 
-# 创建新订单
-barista arabica orders create <plan-id> [--seats <n>] [--period year|month]
+| Feature | Description |
+|---------|-------------|
+| 🤖 **JSON-First Output** | All commands support `--json` for AI parsing |
+| 📦 **Structured Responses** | Consistent `{success, data, meta}` envelope |
+| 🔄 **Idempotent Operations** | Safe for AI retry loops |
+| 🛡️ **Dry-Run by Default** | Destructive operations preview before execution |
+| 🔐 **Secure Storage** | Credentials in system keychain, not env vars |
 
-# 取消订单
-barista arabica orders cancel <order-id>
-```
+### Enterprise Connectivity
 
-#### 发票管理
+| Service | Capabilities |
+|---------|-------------|
+| ☕ **Liberica** | Orders, products, inventory, warehouses, production planning |
+| 🛒 **Arabica** | Subscription plans, billing, invoices, enterprise management |
+| 🔗 **Cross-Service** | Quote from order, sync between systems |
 
-```bash
-# 查看发票列表
-barista arabica invoices list [--year 2026]
+### Operational Safety
 
-# 查看发票详情
-barista arabica invoices get <invoice-id>
+- 📊 **Audit Trail** — Every operation logged with request ID
+- ⚠️ **Confirmation Guards** — `--dry-run` / `--force` for write operations
+- 🏢 **Multi-Tenant Isolation** — Credentials isolated per tenant
 
-# 下载发票 PDF
-barista arabica invoices download <invoice-id> [--output <path>]
-```
+---
 
-#### 用量查看
+## 🔧 Command Reference
 
-```bash
-# 查看当前用量
-barista arabica usage current
+### Core Pattern
 
-# 查看用量历史
-barista arabica usage history [--period 30d|90d|1y]
 ```
-
-#### 企业管理
-
-```bash
-# 查看企业列表
-barista arabica enterprise list
-
-# 查看席位使用
-barista arabica enterprise seats
-
-# 增加席位
-barista arabica enterprise seats add <n>
-
-# 查看/邀请企业成员
-barista arabica enterprise members list
-barista arabica enterprise members invite <email>
+barista <service> <resource> <action> [options]
 ```
 
-#### 访问 Liberica
+### Global Options
 
-```bash
-# 获取 Liberica 访问地址
-barista arabica access url
-```
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--env` | Environment (dev\|test\|prod-cn\|prod-jp) | `dev` |
+| `--tenant` | Tenant name | - |
+| `--json` | JSON output | `false` |
+| `--dry-run` | Preview mode (recommended for AI) | `false` |
+| `--force` | Skip confirmation | `false` |
+| `--page` | Page number | `1` |
+| `--size` | Page size (max items) | `20` |
 
-### 跨服务命令
+### Quick Reference
 
-跨服务命令实现 Liberica 与 Arabica 之间的数据同步和业务流程衔接。
+| Command | Description |
+|---------|-------------|
+| `barista context show` | Show current env/tenant context |
+| `barista context use-env <env>` | Switch environment |
+| `barista liberica orders list --json` | List orders (AI format) |
+| `barista liberica orders get <id> --json` | Get order detail |
+| `barista liberica orders create --dry-run ...` | Preview create |
+| `barista liberica products search --keyword <kw> --json` | Search products |
+| `barista arabica plans list --json` | List subscription plans |
+| `barista arabica invoices list --json` | List invoices |
 
-```bash
-# 从订单生成报价单
-barista cross quote-from-order <order-id> [--target-service arabica]
-
-# 输出示例：
-# ✓ 已生成报价单
-# ┌──────────┬────────────┐
-# │ 属性     │ 值         │
-# ├──────────┼────────────┤
-# │ 订单ID   │ 12345      │
-# │ 报价单ID │ QT-2024-001│
-# │ 金额     │ ¥50,000    │
-# │ 有效期   │ 30天       │
-# └──────────┴────────────┘
-
-# 同步订单状态到 Arabica
-barista cross sync-order <order-id> [--direction liberica-to-arabica]
-```
+**[→ Full Command Reference](./docs/commands/REFERENCE.md)**
 
 ---
 
-## 高级特性
+## 🛡️ AI Safety Guidelines
 
-### Dry-Run 模式
+### 1. Always Dry-Run First
 
-Dry-Run 模式允许你在执行写入操作前预览其影响，避免误操作。
+```typescript
+// ❌ Wrong - executing blindly
+await $`barista liberica orders cancel 12345`
 
-```bash
-# 所有写入操作都支持 --dry-run 选项
-barista liberica orders create --product-id 123 --quantity 100 --dry-run
-
-# 输出示例：
-# 🔍 Dry-Run 模式：操作不会被实际执行
-# ┌─────────────────┬──────────────────────┐
-# │ 操作            │ 创建订单             │
-# ├─────────────────┼──────────────────────┤
-# │ 产品            │ 咖啡机 Pro (ID: 123) │
-# │ 数量            │ 100                  │
-# │ 预计金额        │ ¥50,000              │
-# │ 预计交期        │ 2024-12-31           │
-# │ 影响            │ 新增一条订单记录     │
-# └─────────────────┴──────────────────────┘
-# 
-# ⚠️  确认执行？添加 --confirm 选项或移除 --dry-run
+// ✅ Correct - preview first
+const preview = await $`barista liberica orders cancel 12345 --dry-run`
+// Parse preview, verify correctness, then:
+await $`barista liberica orders cancel 12345 --force`
 ```
 
-**默认 Dry-Run 的操作：**
-
-以下破坏性操作默认启用 Dry-Run 模式，需显式确认：
-
-- 取消订单
-- 删除产品
-- 批量更新
+### 2. Check Success Before Proceeding
 
-### JSON 输出格式
-
-Barista CLI 支持 JSON 输出，便于脚本处理和 AI 集成：
-
-```bash
-barista liberica orders list --json
-
-# 输出示例：
-{
-  "success": true,
-  "data": {
-    "items": [
-      {
-        "id": "12345",
-        "productName": "咖啡机 Pro",
-        "quantity": 100,
-        "status": "in_production",
-        "createdAt": "2024-01-15T10:30:00Z"
-      }
-    ],
-    "pagination": {
-      "page": 1,
-      "size": 20,
-      "total": 150
-    }
-  }
+```typescript
+const result = JSON.parse(stdout)
+if (!result.success) {
+  // Handle error, don't continue
+  throw new Error(result.error?.message || result.meta?.message)
 }
 ```
 
-### CSV 导出格式
-
-Barista CLI 支持 CSV 格式导出，适用于数据分析及 Excel 处理：
+### 3. Use Request IDs for Debugging
 
-```bash
-# 导出字典类型数据为 CSV
-barista liberica dict-types tenant-items --lang ja --all --csv --output ./dict-data.csv
-
-# 输出特性：
-# • UTF-8 with BOM 编码，确保 Excel 正确识别中文
-# • 自动转义特殊字符（逗号、引号、换行符）
-# • 支持自定义输出文件路径
-# • 可配合 --json 同时输出两种格式
+```typescript
+const { meta } = JSON.parse(stdout)
+console.log(`Request ID: ${meta.requestId}`)
 ```
 
-CSV 文件采用 UTF-8 with BOM 编码，确保在 Microsoft Excel 等工具中正确显示中、日、越等 Unicode 字符。
+### 4. Respect Rate Limits
+
+- Add delays between bulk operations
+- Use `--size 100` for bulk fetches
+- Cache responses when appropriate
 
 ---
 
-## 配置说明
+## ⚙️ Configuration
 
-### 配置文件
+### File Location
 
-配置文件位于 `~/.barista/config.yaml`：
+`~/.barista/config.yaml`
 
-```yaml
-# Barista CLI 配置文件
+### Quick Config
 
-# 默认上下文设置
+```yaml
 defaults:
-  env: dev
-  tenant: electionjp
+  env: prod-cn
+  tenant: your-tenant
   service: liberica
 
-# 环境配置
 environments:
-  dev:
-    liberica:
-      baseUrl: "https://{tenant}-dev.newpeaksh.com"
-      timeout: 30000
-    arabica:
-      baseUrl: "https://arabica-dev.newpeaksh.com"
-      timeout: 30000
-  
-  test:
-    liberica:
-      baseUrl: "https://{tenant}-test.newpeaksh.com"
-      timeout: 30000
-    arabica:
-      baseUrl: "https://arabica-test.newpeaksh.com"
-      timeout: 30000
-  
   prod-cn:
     liberica:
       baseUrl: "https://{tenant}.newpeaksh.com"
@@ -632,258 +270,71 @@ environments:
     arabica:
       baseUrl: "https://www.newpeaksh.com"
       timeout: 60000
-  
-  prod-jp:
-    liberica:
-      baseUrl: "https://{tenant}.newpeakjp.com"
-      timeout: 60000
-    arabica:
-      baseUrl: "https://members.newpeakjp.com"
-      timeout: 60000
-
-# 输出配置
-output:
-  format: table  # table | json
-  color: true
-  timestamp: true
 ```
 
-### 多租户配置
-
-支持配置多个租户，快速切换：
+### Authentication
 
 ```bash
-# 添加租户配置
-barista config add-tenant \
-  --name customer-a \
-  --liberica-id customer-a-id \
-  --arabica-id customer-a-arabica-id
+# Credential login (recommended)
+barista liberica auth login <env> <tenant> <username> <password>
 
-# 列出已配置租户
-barista config list-tenants
+# Check auth status
+barista auth status
 
-# 快速切换租户
-barista context use-tenant customer-a
+# Logout
+barista auth logout --service liberica --env prod-cn
 ```
 
 ---
 
-## AI 集成
-
-Barista CLI 专为 AI 编程助手优化，特别是 Claude Code。
-
-### Claude Code 使用示例
-
-```typescript
-// 在 Claude Code 中使用 Barista CLI
-// 示例：获取订单列表并分析
-
-const result = await $`barista liberica orders list --json --page 1 --size 10`;
-const orders = JSON.parse(result.stdout);
-
-// 分析订单数据
-const analysis = orders.data.items.map(order => ({
-  id: order.id,
-  status: order.status,
-  amount: order.amount
-}));
-```
-
-### Skills 文件
-
-Barista CLI 提供 Claude Code Skills 文件，位于：
-
-```
-~/.barista/claude/skills/
-├── orders.md       # 订单管理技能
-├── products.md     # 产品管理技能
-├── quotes.md       # 报价管理技能
-└── customers.md    # 客户管理技能
-```
-
-**示例 Skills 文件：**
-
-```markdown
-# 订单管理技能
-
-## 列出待处理订单
-
-当用户询问待处理订单时：
+## ❓ Troubleshooting
 
-1. 执行命令：barista liberica orders list --status pending --json
-2. 解析返回的 JSON
-3. 总结订单数量和总金额
-4. 列出前 5 个订单的关键信息
-
-## 创建新订单
-
-当用户需要创建订单时：
-
-1. 确认产品 ID 和数量
-2. 使用 dry-run 预览：barista liberica orders create --dry-run ...
-3. 用户确认后执行实际命令
-```
-
-### AI 友好的输出
-
-所有命令都支持 `--json` 选项，返回结构化的 JSON 数据：
+### Auth Failures
 
 ```bash
-# 查询带结构化输出
-barista liberica orders get 12345 --json
-
-{
-  "success": true,
-  "data": {
-    "id": "12345",
-    "status": "in_production",
-    "product": {
-      "id": "100",
-      "name": "咖啡机 Pro"
-    },
-    "quantity": 100,
-    "amount": 50000,
-    "timeline": {
-      "created": "2024-01-15T10:30:00Z",
-      "delivery": "2024-02-15"
-    }
-  },
-  "meta": {
-    "requestId": "req-abc123",
-    "timestamp": "2024-01-15T10:30:00Z"
-  }
-}
-```
-
----
-
-## 开发指南
+# Check current status
+barista auth status
 
-### 项目结构
+# Re-authenticate
+barista liberica auth login prod-cn your-tenant your-username your-password
 
-```
-coffee-barista-cli/
-├── bin/
-│   └── barista.js              # 入口文件
-├── src/
-│   ├── commands/               # 命令实现
-│   │   ├── context/            # 上下文管理命令
-│   │   ├── auth/               # 认证命令
-│   │   ├── liberica/           # Liberica 服务命令
-│   │   │   ├── orders.js
-│   │   │   ├── products.js
-│   │   │   └── production.js
-│   │   ├── arabica/            # Arabica 服务命令
-│   │   │   ├── products.js
-│   │   │   ├── quotes.js
-│   │   │   └── customers.js
-│   │   └── cross/              # 跨服务命令
-│   ├── core/                   # 核心模块
-│   │   ├── auth.js             # 认证管理
-│   │   ├── config.js           # 配置管理
-│   │   ├── context.js          # 上下文管理
-│   │   └── api-client.js       # API 客户端
-│   ├── utils/                  # 工具函数
-│   │   ├── formatter.js        # 输出格式化
-│   │   ├── validator.js        # 参数验证
-│   │   └── keychain.js         # 密钥链操作
-│   └── templates/              # 模板文件
-├── skills/                     # Claude Code Skills
-├── tests/                      # 测试文件
-├── package.json
-└── README.md
+# Check context
+barista context show
 ```
 
-### 本地开发
+### API Errors
 
 ```bash
-# 1. 克隆仓库
-git clone https://gitlab.newpeaksh.com/coffee/coffee-barista-cli.git
-cd coffee-barista-cli
-
-# 2. 安装依赖
-npm install
-
-# 3. 链接到全局（开发模式）
-npm link
-
-# 4. 验证链接
-barista --version
-
-# 5. 运行测试
-npm test
+# Always use --json to get error codes
+barista liberica orders list --json
 
-# 6. 代码检查
-npm run lint
+# Error response includes requestId for debugging
+# "requestId": "req-abc123"
 ```
 
-### 添加新命令
-
-**重要**：新增命令必须遵循 [命令设计规范](./docs/COMMAND_DESIGN_SPEC.md)，包含设计文档编写、技术评审等完整流程。
-
-详细步骤请参考：
-- [完整命令参考](./docs/commands/REFERENCE.md) - 所有命令清单和开发优先级
-- [命令设计规范文档](./docs/COMMAND_DESIGN_SPEC.md#5-命令开发流程规范)
-- [命令开发指南](./docs/COMMANDS.md)
-
----
-
-## 贡献指南
-
-我们欢迎所有形式的贡献，包括但不限于：
-
-- 🐛 报告 Bug
-- 💡 提出新功能建议
-- 📝 改进文档
-- 🔧 提交代码修复
-- ✨ 添加新功能
-
-### 提交规范
-
-请遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
+### Timeout Issues
 
 ```bash
-# 修复 Bug
-fix: 修复订单列表分页问题
+# Switch to closer environment
+barista context use-env dev
 
-# 添加功能
-feat: 添加库存查询命令
-
-# 文档更新
-docs: 更新 README 中的环境映射
-
-# 代码重构
-refactor: 重构 API 客户端错误处理
+# Or adjust timeout in config.yaml
 ```
 
-### 开发流程
-
-1. Fork 本仓库
-2. 创建功能分支：`git checkout -b feature/my-feature`
-3. 提交更改：`git commit -m 'feat: add some feature'`
-4. 推送分支：`git push origin feature/my-feature`
-5. 创建 Pull Request
-
 ---
 
-## 相关项目
+## 📚 Related Projects
 
-| 项目 | 描述 | 链接 |
-|------|------|------|
-| ☕ Liberica Backend | 生产管理 SaaS 后端 | [coffee-liberica-end](https://gitlab.newpeaksh.com/coffee/coffee-liberica-end) |
-| 🖥️ Liberica Frontend | 生产管理 Web 前端 | [coffee-liberica-front](https://gitlab.newpeaksh.com/coffee/coffee-liberica-front) |
-| 📱 Liberica Mobile | 生产管理移动端 | [coffee-liberica-mobile-front](https://gitlab.newpeaksh.com/coffee/coffee-liberica-mobile-front) |
-| 🛒 Arabica Backend | 在线订阅 SaaS 服务后端 | [coffee-arabica-end](https://gitlab.newpeaksh.com/coffee/coffee-arabica-end) |
-| 🌐 Arabica Frontend | 在线订阅 SaaS 服务前端 | [coffee-arabica-front](https://gitlab.newpeaksh.com/coffee/coffee-arabica-front) |
+| Project | Description |
+|---------|-------------|
+| ☕ Liberica Backend | Production management SaaS backend |
+| 🖥️ Liberica Frontend | Production management web UI |
+| 📱 Liberica Mobile | Production management mobile app |
+| 🛒 Arabica Backend | Online subscription SaaS backend |
+| 🌐 Arabica Frontend | Online subscription web UI |
 
 ---
 
-## 许可证
+## 📄 License
 
 [MIT](LICENSE) © Newpeak Technology
-
----
-
-<p align="center">
-  用 ☕ 驱动生产力
-</p>