docs: npx-based install (verified) — CLI via git+https, skill via skills add

- CLI: npx git+https://... (ad-hoc) / npm i -g git+https://... (permanent)
- skill: npx -y skills add https://... -g -y --copy (installs to
  ~/.zcode/skills + ~/.claude/skills + ~/.agents/skills + ~40 agents)
- prefix trap documented: npm/npx NEED git+, skills add must NOT have it
- install.sh kept as offline/no-npm fallback

README.md

@@ -15,14 +15,31 @@
 
 ## 安装
 
+仓库地址（https 匿名可读）：`https://gitea.inkreach.cc/inkreachhub/inkreach-teable-cli.git`
+
+**CLI —— npx 免安装直接用**（首次自动 clone + 构建，之后走缓存）：
+
 ```bash
-git clone ssh://git@gitea.inkreach.cc:2222/inkreachhub/inkreach-teable-cli.git
+npx git+https://gitea.inkreach.cc/inkreachhub/inkreach-teable-cli.git --help
-cd inkreach-teable-cli
-bash skills/inkreach-teable/scripts/install.sh
 ```
 
-安装脚本会：构建 CLI → 全局链接 `inkreach-teable` 命令 → 把 skill 安装到
+**CLI —— 全局安装**（获得裸 `inkreach-teable` 命令）：
-`~/.zcode/skills/inkreach-teable`（用户级，任意工作区可用）。更新后重跑一次即可。
+
+```bash
+npm i -g git+https://gitea.inkreach.cc/inkreachhub/inkreach-teable-cli.git
+```
+
+**Skill —— 一条命令装到所有 Agent**（`~/.zcode/skills/`、`~/.claude/skills/`、`~/.agents/skills/` 等）：
+
+```bash
+npx -y skills add https://gitea.inkreach.cc/inkreachhub/inkreach-teable-cli.git -g -y --copy
+```
+
+> ⚠️ **前缀差异**：npx/npm 安装 CLI 必须带 **`git+`** 前缀（裸 https 会被 npm 当成 tarball 下载而报 `TAR_BAD_ARCHIVE`）；`skills add` 必须用**不带** `git+` 的纯 https URL（它把 URL 直接传给 git，带前缀会 clone 失败）。
+
+更新：CLI 用 `npm rm -g @inkreach/teable-cli && npm i -g git+https://…` 重装；skill 用 `npx -y skills update` 或重跑上面的 `skills add`。
+
+离线 / 无 npm 环境的兜底：clone 仓库后运行 `bash skills/inkreach-teable/scripts/install.sh`（构建 + 链接命令 + 复制 skill 到 `~/.zcode/skills/`）。
 
 ## 配置
 
@@ -48,10 +65,11 @@ pnpm typecheck
 
 ```text
 请为操作 inkreach-teable 实例安装 inkreach-teable CLI 及配套 skill：
-1. 克隆工具仓库：
+1. 全局安装 CLI：
-   git clone ssh://git@gitea.inkreach.cc:2222/inkreachhub/inkreach-teable-cli.git ~/deployments/inkreach-teable-cli
+   npm i -g git+https://gitea.inkreach.cc/inkreachhub/inkreach-teable-cli.git
-2. 在仓库内运行安装脚本（构建 CLI、全局链接命令、安装 skill 到 ~/.zcode/skills/）：
+   （免安装用法：npx git+https://gitea.inkreach.cc/inkreachhub/inkreach-teable-cli.git <子命令>）
-   bash ~/deployments/inkreach-teable-cli/skills/inkreach-teable/scripts/install.sh
+2. 安装 skill 到用户级（注意：这条必须用不带 git+ 前缀的纯 https URL）：
+   npx -y skills add https://gitea.inkreach.cc/inkreachhub/inkreach-teable-cli.git -g -y --copy
 3. 配置认证并验证（PAT 从 Web UI Settings → Personal Access Tokens 获取）：
    inkreach-teable auth login --endpoint http://<后端地址> --token <PAT> --base-id bseXXX
    inkreach-teable auth status

skills/inkreach-teable/SKILL.md

@@ -24,7 +24,7 @@ Respond in the user's language. Keep answers concise and action-oriented.
 
 ## 1. Prerequisites
 
-- Install the CLI if missing: `bash scripts/install.sh` (relative to this skill dir).
+- Install the CLI if missing: `npm i -g git+https://gitea.inkreach.cc/inkreachhub/inkreach-teable-cli.git` (the `git+` prefix is REQUIRED for npm/npx; ad-hoc without installing: `npx git+https://gitea.inkreach.cc/inkreachhub/inkreach-teable-cli.git <cmd>`). Offline fallback: `bash scripts/install.sh` relative to this skill dir in a repo clone.
 - **Configure once**: `inkreach-teable auth login --endpoint http://localhost:3003 --token <PAT> [--base-id bseXXX]`; verify with `auth status`. PAT comes from `auth token create --name x` (full token shown **once**) or the web UI (Settings → Personal Access Tokens).
 - `--json` on any command returns raw JSON (for agent parsing). Fallback for unknown commands: `inkreach-teable <cmd> --help`.
 - **Read on demand**: consult the guide linked for your module when doing non-trivial work — no need to read everything up front.