@thinkingai/ae-cli 6.0.52 → 6.0.54

package/README.md

@@ -15,8 +15,9 @@ The CLI is designed around:
 ## Requirements
 
 - Node.js 20 or later.
+- macOS, Linux, or native Windows (PowerShell / Command Prompt); WSL is optional.
 - Access to the npm registry for CLI installation.
-- Access to GitHub when installing Skills initially or when the local Skills fallback cannot be used.
+- Access to GitHub only when the bundled Skills source cannot be used.
 
 ## Installation
 
@@ -25,10 +26,12 @@ For setup through Codex, Claude Code, Cursor, or another terminal-capable AI Age
 Install the public CLI and Agent Skills:
 
 ```bash
-npm install -g @thinkingai/ae-cli
-npx -y skills add ThinkingAIAgenticEngine/ae-cli -g -y
+npx @thinkingai/ae-cli@latest install
+npx @thinkingai/ae-cli@latest install --format json
 ```
 
+The installer checks Node.js 20+, installs and verifies the CLI, then installs matching Skills globally in `~/.agents/skills`, writing the shared files once before automatically distributing copies to clients that need their own directory. No Agent selection is needed; Codex and Cursor can share these Skills even when installed later. `--dry-run`, `--format json`, and optional `--host <AE_HOST>` are supported. Unrelated project-only client warnings are hidden after successful verification; missing files and YAML errors remain failures. Being logged out is not an installation failure. See the [installation guide](./cli-installation-guide.md).
+
 The Skills teach supported coding Agents, including Claude Code, Codex, Cursor, and similar tools, how to discover and call `ae-cli`.
 
 Install optional, approved scenario Skills with an interactive category picker:
@@ -57,6 +60,10 @@ ae-cli update
 ae-cli update --dry-run
 ```
 
+Updates use the same global Skills installation and verification as `install`. Older packages need no installer or generated manifest: their bundled Skills define the expected contents. If Skills fail after the CLI installs, the result reports partial completion and can be retried.
+
+Automatic synchronization runs during normal commands after login; host version checks are cached for up to 24 hours. `ae-cli update --host <AE_HOST>` checks immediately. After a downgrade, future updates run the older CLI's own updater, including its historical limitations. To use the new installer logic while following an older host, run `npx @thinkingai/ae-cli@latest update --host <AE_HOST>`; the target remains the host-required version.
+
 `ae-cli update` installs the exact version required by the active host rather than npm `latest`. It synchronizes Skills from the installed npm package first and uses the matching GitHub tag only as a fallback.
 
 Starting with the `6.0.37` and `6.1.9` release lines, ordinary business commands can automatically upgrade or downgrade the CLI to the host-required version. After a successful synchronization, the old process exits with `AE_CLI_VERSION_SYNCED`; re-run the original command so it executes with the new CLI and Skills. Installation failures are reported without replacing the business command's JSON output.
@@ -126,7 +133,7 @@ The table covers every current root command individually. Use `ae-cli --help` fo
 | Engage | `engage-workbench` | Engage workbench and to-do management |
 | Engage | `engage-query` | Engage queries, asynchronous exports, and artifact management |
 | DataOps | `dataops_repo` | Data-warehouse and data-source management |
-| DataOps | `dataops_datatable` | Data-table lifecycle management |
+| DataOps | `dataops_datatable` | Table/view lifecycle management, including recycling, recycle-bin discovery, and permanent deletion |
 | DataOps | `dataops_flow` | Development flows, scheduling, and backfill-job management |
 | DataOps | `dataops_ide` | IDE queries and result downloads |
 | DataOps | `dataops_integration` | Data-integration task management |
@@ -134,15 +141,19 @@ The table covers every current root command individually. Use `ae-cli --help` fo
 | Agent platform | `kb` | Knowledge-base lifecycle, LLM Q&A, and deterministic index/grep/read retrieval |
 | Agent platform | `agent` | Agents, approvals, automations, models, MCP servers, Skills, attachments, credentials, and sandbox tools |
 | Agent platform | `context` | Read the current product-page context authorized for the active Agent Run |
-| Agent platform | `memory` | User memory, Top-K context writing, and actual-usage accounting |
+| Agent platform | `memory` | AgentSpace memory, drafts, shared review, extraction jobs, revisions, and state transitions |
 | Agent platform | `team` | Agent Team and TeamRun execution, chat, results, and artifacts |
 | Agent platform | `system` | Root/admin management of members, sandboxes, tools, models, usage, quotas, and channels |
 | General tools | `capability` | Capability discovery, schema inspection, validation, dry-run, and generic execution |
 | General tools | `auth` | Host-scoped login, status, and multi-account management |
 | General tools | `config` | Add, switch, rename, and remove Host environments |
-| General tools | `sync` | Push or pull local Skills and MCPs to/from the Agent application |
-| General tools | `model` | Inspect and switch the current workspace model inside an Agent sandbox |
+| General tools | `sync` | Push or pull local Skills and MCPs to/from the Agent application; blocked in AgentSpace context |
+| General tools | `model` | Inspect and switch the current workspace model inside an Agent sandbox; blocked in AgentSpace context |
 | General tools | `update` | Synchronize CLI and Skills to the version required by the current Host |
+| General tools | `install` | Install and verify CLI and matching global Skills |
+| Agent platform | `workspace` | AgentSpace context, profiles, capabilities, members, activities, and lifecycle |
+| Agent platform | `things` | Workspace issues, collaborators, timeline, archive, and restore |
+| Agent platform | `automation` | Automation configuration, execution, history, and results |
 <!-- root-command-surface:end -->
 
 ## Capability Gateway
@@ -164,6 +175,10 @@ Use `validate` while fixing complex nested input. Use `dry-run` when you need th
 
 Gateway-backed features follow the [Capability command admission rules](docs/capability-command-admission.md). Common workflows may have curated commands; long-tail capabilities remain dynamically discoverable.
 
+Event-report presentation is separate from its query definition: `analysis report create|update --presentation '{"chart_type":"bar","table_layout":"event"}'` sets the source chart/result-table layout, and `report get` returns its effective presentation. On same-model updates, omit presentation to preserve the saved chart and result-table layout. For a table card on an analysis board, use `analysis dashboard-report get|update` with exact project/dashboard/report IDs; `update --chart-type table --table-layout event --date-outside false` changes only that card, preserving the source definition and other boards. This presentation contract currently supports event reports only. See [report update](skills/ae-analysis/references/report_update.md) and [card update](skills/ae-analysis/references/dashboard_report_update.md).
+
+Event combination charts use source `presentation.chart_type=combo` and `series` items `{metric_index:1,type:"bar",axis:"primary"}` (`type=bar|line`, `axis=primary|secondary`). Indexes are current 1-based `definition.metrics` positions; updates use the current report version, subset patches, or explicit `series: []`/`chart_type=line` resets. Board trends inherit source series, so source edits affect its other trend cards; `dashboard-report update --chart-type combo` selects existing combo, not a card-local override. Cumulative line is not combo. See [combination-chart scope and safety](skills/ae-analysis/references/event_report_presentation.md).
+
 `analysis user-tag create|update` supports periodic refresh in one command: pass `--auto-refresh-schedule '{"frequency":"daily","time":"02:30"}'` (also weekly/monthly), or `--auto-refresh-cron`. Use `--enable-auto-refresh false` to disable it. Scheduling-only updates do not recompute; omitted settings preserve the existing plan. See the [tag create](skills/ae-analysis/references/user_tag_create.md) and [tag update](skills/ae-analysis/references/user_tag_update.md) references.
 
 ## Authentication and Environments
@@ -176,6 +191,10 @@ For scripts and agents, use the non-interactive subcommands:
 ```bash
 ae-cli auth login --host https://host-a.example.com
 ae-cli auth status --host https://host-a.example.com
+# Import a CLI token copied from External Access Management (hidden prompt)
+ae-cli auth set-token --host https://host-a.example.com
+# Non-interactive input for local scripts or tests
+printf '%s' "$AE_CLI_TOKEN" | ae-cli auth set-token --host https://host-a.example.com --token-stdin
 # For the uncommon case where one Host needs multiple accounts
 ae-cli auth login --host https://host-a.example.com --add
 ae-cli auth list --host https://host-a.example.com
@@ -195,6 +214,8 @@ ae-cli config remove pre-production --yes
 
 A regular `auth login` keeps the simple one-Host/one-account behavior and replaces credentials for that Host; use `--add` only when other accounts must be retained. `auth status` reports CLI-token state only. A new backend can also provide account identity and expiration; when an older backend does not support `/validate`, the CLI preserves the historical behavior of trusting the stored CLI token and omits `account` instead of returning null fields.
 
+`auth set-token` is for local use with a `cli_` token copied from External Access Management. It prompts without echo by default; `--token-stdin` supports non-interactive local testing. The CLI validates the token against the target Host before replacing the stored credential, encrypts it in the existing per-Host vault, and never includes the value in command output. Add `--add` to retain other accounts for the same Host.
+
 The new CLI persists only CLI tokens, never access or refresh tokens. Multiple accounts live in an encrypted V1 vault while the active account is projected into the historical file shape for automatic downgrades. When the CLI upgrades again, it reconciles login, switch, or logout changes made by the old CLI.
 
 Login uses a cross-platform device-code flow. Use `--no-browser` when the environment cannot open a browser.
@@ -268,7 +289,7 @@ ae-cli agent +list-agents
 ae-cli agent +list-models
 ae-cli agent +list-mcps
 ae-cli agent +list-skills
-ae-cli agent +list-automations
+ae-cli automation list
 ae-cli agent +list-attachments
 ae-cli agent approval-type list
 ae-cli agent approval-request list --status pending
@@ -311,14 +332,17 @@ The npm package includes the same `skills/` directory used by the public reposit
 | `ae-community` | Community analysis and reporting |
 | `ae-data-integration` | Local CSV/JSON/Excel inspection, mapping, conversion, upload, and reusable handoff |
 | `ae-kb`, `ae-kb-discovery` | Knowledge-base lifecycle, Q&A, deterministic retrieval, and read-only knowledge-base discovery |
-| `ae-agent`, `ae-system`, `ae-team` | Agent resources and user memory, administration, and TeamRun workflows |
+| `ae-workspace` | AgentSpace context, profiles, capabilities, members, activities, and lifecycle |
+| `ae-things`, `ae-things-progress`, `ae-things-review` | Workspace issues, progress digests, and review summaries |
+| `ae-automation` | Automation configuration, execution, history, and results |
+| `ae-agent`, `ae-system`, `ae-team` | Agent resources, AgentSpace memory, administration, and TeamRun workflows |
 | `ae-generate-tracking-plan`, `ae-generate-tracking-code` | Tracking-plan and tracking-code generation |
 | `ae-data-integration-helper` | SDK and LogBus2 integration guidance |
 
 Reinstall all public Skills with:
 
 ```bash
-npx -y skills add ThinkingAIAgenticEngine/ae-cli -g -y
+ae-cli install
 ```
 
 ## Development
@@ -361,6 +385,7 @@ npm run verify:readme
 npm run verify:auth-credentials
 npm run verify:update-check
 npm run verify:version-sync
+npm run verify:install
 ```
 
 ## Changelog

package/README.zh.md

@@ -15,8 +15,9 @@ CLI 的核心设计包括：
 ## 环境要求
 
 - Node.js 20 或更高版本。
+- 支持 macOS、Linux 和原生 Windows（PowerShell / CMD），无需安装 WSL。
 - 安装 CLI 时能够访问 npm 仓库。
-- 首次安装 Skills，或本地 Skills 来源不可用时，能够访问 GitHub。
+- 内置 Skills 来源不可用时，能够访问 GitHub。
 
 ## 安装
 
@@ -24,15 +25,17 @@ CLI 的核心设计包括：
 
 可直接复制给 Agent，并把 `<AE_HOST>` 替换为你的 AE 地址：
 
-> 请阅读 https://raw.githubusercontent.com/ThinkingAIAgenticEngine/ae-cli/main/cli-installation-guide.md 并按说明帮我安装或升级 AE CLI。我的 AE 地址是 `<AE_HOST>`。只安装 AE CLI 和配套 Skills，不要修改当前项目；遇到登录授权或需要管理员权限时请暂停并提示我。
+> 请按[安装指南](./cli-installation-guide.md)中的“AI installation prompt”帮助我安装 AE CLI；全局安装 Skills，并根据最终 CLI/Skills 验证结果判断成功。
 
 安装公开版 CLI 和 Agent Skills：
 
 ```bash
-npm install -g @thinkingai/ae-cli
-npx -y skills add ThinkingAIAgenticEngine/ae-cli -g -y
+npx @thinkingai/ae-cli@latest install
+npx @thinkingai/ae-cli@latest install --format json
 ```
 
+安装器检查 Node.js 20+、安装并验证 CLI，再将同版本 Skills 全局安装到 `~/.agents/skills`，公共文件只写入一次，再自动向需要独立目录的客户端分发副本，无需选择 Agent；之后安装的 Codex、Cursor 也可共享这些 Skills。支持 `--dry-run`、`--format json` 和可选的 `--host <AE_HOST>`。验证成功后不显示无关的项目级客户端告警；文件缺失和 YAML 错误仍判为失败。未登录不算安装失败。详见[安装指南](./cli-installation-guide.md)。
+
 Skills 会帮助 Claude Code、Codex、Cursor 等编码 Agent 理解、发现并调用 `ae-cli`。
 
 按业务分类交互安装可选的已准出场景 Skill：
@@ -61,6 +64,10 @@ ae-cli update
 ae-cli update --dry-run
 ```
 
+更新与 `install` 复用全局 Skills 安装和校验。旧包无需包含安装器或生成的清单，直接以目标包内置 Skills 为准。CLI 安装后 Skills 失败会返回部分成功信息，修复后可重复执行。
+
+自动同步在登录后的普通命令中触发，集群版本检查最长缓存 24 小时；`ae-cli update --host <AE_HOST>` 可立即查询。降级后，后续更新由旧版 CLI 自身执行，也受旧版实现限制。需要用新安装逻辑匹配旧集群时，可运行 `npx @thinkingai/ae-cli@latest update --host <AE_HOST>`，目标仍是集群要求的版本。
+
 `ae-cli update` 安装当前 Host 要求的精确版本，不依赖 npm `latest`。更新时优先从已安装的 npm 包同步 Skills，本地来源失败后才回退到对应的 GitHub tag。
 
 从 `6.0.37` 和 `6.1.9` 维护线开始，普通业务命令可以自动升级或降级到环境要求的版本。同步成功后，旧进程会返回 `AE_CLI_VERSION_SYNCED`；重新执行原命令，即可使用新的 CLI 和 Skills。安装失败会给出提示，但不会用安装输出污染业务命令的 JSON 结果。
@@ -130,7 +137,7 @@ ae-cli capability list --domain analysis --jq '.data.capabilities[] | .id'
 | 运营 | `engage-workbench` | 运营工作台和待办管理 |
 | 运营 | `engage-query` | 运营查询、异步导出和产物管理 |
 | DataOps | `dataops_repo` | 数仓和数据源管理 |
-| DataOps | `dataops_datatable` | 数据表生命周期管理 |
+| DataOps | `dataops_datatable` | 表/视图生命周期管理，包括回收、查询回收站与彻底删除 |
 | DataOps | `dataops_flow` | 开发流程、调度和补数作业管理 |
 | DataOps | `dataops_ide` | IDE 查询及结果下载 |
 | DataOps | `dataops_integration` | 数据集成任务管理 |
@@ -138,15 +145,19 @@ ae-cli capability list --domain analysis --jq '.data.capabilities[] | .id'
 | Agent 平台 | `kb` | 知识库生命周期、LLM 问答及确定性的 index/grep/read 检索 |
 | Agent 平台 | `agent` | Agent、审批、自动化、模型、MCP、Skills、附件、凭证和沙盒工具 |
 | Agent 平台 | `context` | 读取当前 Agent Run 已授权的产品页面上下文 |
-| Agent 平台 | `memory` | 用户记忆、Top-K 上下文写入和实际采用计数 |
+| Agent 平台 | `memory` | AgentSpace 记忆、草稿、共享审核、提取任务、版本与状态治理 |
 | Agent 平台 | `team` | Agent Team 和 TeamRun 的执行、对话、结果及产物 |
 | Agent 平台 | `system` | root/admin 的成员、沙盒、工具、模型、用量、配额和渠道管理 |
 | 通用工具 | `capability` | 能力发现、Schema 查看、参数校验、dry-run 和通用执行 |
 | 通用工具 | `auth` | 按 Host 登录、查看状态及管理同一 Host 的多个账号 |
 | 通用工具 | `config` | 添加、切换、重命名和删除 Host 环境 |
-| 通用工具 | `sync` | 在本地工作区与 Agent 应用之间推送或拉取 Skills 和 MCP |
-| 通用工具 | `model` | 在 Agent 沙盒中查看并切换当前工作区模型 |
+| 通用工具 | `sync` | 在本地工作区与 Agent 应用之间推送或拉取 Skills 和 MCP；在 AgentSpace 上下文中禁用 |
+| 通用工具 | `model` | 在 Agent 沙盒中查看并切换当前工作区模型；在 AgentSpace 上下文中禁用 |
 | 通用工具 | `update` | 将 CLI 和 Skills 同步到当前 Host 要求的版本 |
+| 通用工具 | `install` | 一键安装、验证 CLI 和同版本全局 Skills |
+| Agent 平台 | `workspace` | AgentSpace 上下文、资料、能力、成员、动态与生命周期 |
+| Agent 平台 | `things` | 工作空间事项、协作成员、时间线、归档与恢复 |
+| Agent 平台 | `automation` | 自动化配置、执行、历史和结果 |
 <!-- root-command-surface:end -->
 
 ## Capability Gateway
@@ -168,6 +179,10 @@ ae-cli capability run analysis.report.list --input input.json
 
 Gateway 命令遵循 [Capability 命令收录规则](docs/capability-command-admission.md)。常见工作流可以提供精选命令，长尾能力则保持动态发现。
 
+事件报表的展示配置与查询定义分开：`analysis report create|update --presentation '{"chart_type":"bar","table_layout":"event"}'` 设置原报表图形及结果表布局，`report get` 返回实际生效的展示配置。同模型更新时省略 presentation 可保留原有图形和结果表布局。看板表格卡片使用 `analysis dashboard-report get|update`，明确项目、看板和报表 ID；`update --chart-type table --table-layout event --date-outside false` 只改变该卡片，保留原报表定义及其他看板。本次展示配置契约仅支持事件报表。详见[报表更新](skills/ae-analysis/references/report_update.md)和[卡片更新](skills/ae-analysis/references/dashboard_report_update.md)。
+
+事件组合图使用原报表 `presentation.chart_type=combo` 和 `series` 项 `{metric_index:1,type:"bar",axis:"primary"}`（`type=bar|line`，`axis=primary|secondary`）。索引是当前 `definition.metrics` 从 1 开始的位置；更新使用当前报表版本，支持部分指标补丁及显式 `series: []` / `chart_type=line` 重置。看板趋势图继承原报表系列，修改源系列会影响该报表的其他趋势卡片；`dashboard-report update --chart-type combo` 选择已有组合图，不提供卡片独立覆盖。累计折线不等于组合图。详见[组合图作用域与安全规则](skills/ae-analysis/references/event_report_presentation.md)。
+
 `analysis user-tag create|update` 支持一次配置自动更新：传入 `--auto-refresh-schedule '{"frequency":"daily","time":"02:30"}'`（也支持每周、每月），或使用 `--auto-refresh-cron`。用 `--enable-auto-refresh false` 关闭自动更新。仅修改调度计划不触发即时重算；省略调度参数则保留原计划。详见[创建标签](skills/ae-analysis/references/user_tag_create.md)和[更新标签](skills/ae-analysis/references/user_tag_update.md)。
 
 ## 认证与多环境
@@ -180,6 +195,10 @@ Gateway 命令遵循 [Capability 命令收录规则](docs/capability-command-adm
 ```bash
 ae-cli auth login --host https://host-a.example.com
 ae-cli auth status --host https://host-a.example.com
+# 导入从“外部访问管理”复制的 CLI Token（隐藏输入）
+ae-cli auth set-token --host https://host-a.example.com
+# 本地脚本或测试使用非交互输入
+printf '%s' "$AE_CLI_TOKEN" | ae-cli auth set-token --host https://host-a.example.com --token-stdin
 # 少量需要同一 Host 多账号的场景
 ae-cli auth login --host https://host-a.example.com --add
 ae-cli auth list --host https://host-a.example.com
@@ -199,6 +218,8 @@ ae-cli config remove pre-production --yes
 
 普通 `auth login` 保持一个 Host 一个账号的简单语义，并替换该 Host 已保存的账号；仅在需要时使用 `--add` 保留其他账号。`auth status` 只展示 CLI Token 状态；新版后端可同时返回账号和到期时间，旧版后端不支持 `/validate` 时仍按历史行为信任本地 CLI Token，且不会输出含 null 字段的 `account`。
 
+`auth set-token` 用于在本地导入从“外部访问管理”复制的 `cli_` Token。默认使用不回显的隐藏输入，`--token-stdin` 支持本地测试等非交互场景。CLI 会先向目标 Host 校验 Token，再替换本地凭证，并写入现有的按 Host 加密凭据库；命令输出不会包含 Token。需要保留同一 Host 的其他账号时增加 `--add`。
+
 新版 CLI 只持久化 CLI Token，不保存 access token 或 refresh token。多账号保存在加密的 V1 凭据文件中，同时维护旧文件格式的当前账号投影，保证 CLI 自动降级后仍可登录；再次升级时会合并旧 CLI 对投影的登录、切换或退出变更。
 
 登录使用跨平台设备码流程。当前环境无法打开浏览器时，可使用 `--no-browser`。
@@ -272,7 +293,7 @@ ae-cli agent +list-agents
 ae-cli agent +list-models
 ae-cli agent +list-mcps
 ae-cli agent +list-skills
-ae-cli agent +list-automations
+ae-cli automation list
 ae-cli agent +list-attachments
 ae-cli agent approval-type list
 ae-cli agent approval-request list --status pending
@@ -322,7 +343,7 @@ npm 包内包含与公开仓库一致的 `skills/` 目录：
 重新安装全部公开 Skills：
 
 ```bash
-npx -y skills add ThinkingAIAgenticEngine/ae-cli -g -y
+ae-cli install
 ```
 
 ## 开发
@@ -365,6 +386,7 @@ npm run verify:readme
 npm run verify:auth-credentials
 npm run verify:update-check
 npm run verify:version-sync
+npm run verify:install
 ```
 
 ## 更新日志

package/bin/ae-cli.js

@@ -1,2 +1,7 @@
 #!/usr/bin/env node
-import '../dist/index.js';
+if (Number(process.versions.node.split('.')[0]) < 20) {
+  console.error('AE CLI requires Node.js 20 or later. Select a supported Node.js runtime and rerun.');
+  process.exitCode = 1;
+} else {
+  await import('../dist/index.js');
+}

package/cli-installation-guide.md

@@ -0,0 +1,91 @@
+# AE CLI Installation Guide
+
+Use the same one-command installer from a terminal or an AI Agent:
+
+```bash
+npx @thinkingai/ae-cli@latest install
+```
+
+No Agent selection is required. Optional usage:
+
+```bash
+npx @thinkingai/ae-cli@latest install --format json
+npx @thinkingai/ae-cli@latest install --host <AE_HOST>
+npx @thinkingai/ae-cli@latest install --dry-run
+```
+
+## Requirements and global Skills
+
+Node.js 20 or later, npm, and npx must be available. The installer does not change the default Node version, use sudo, or modify project dependencies. macOS, Linux, and native Windows are supported. On Windows, use PowerShell or Command Prompt; WSL is optional. Global Skills are installed under the current user's home directory on each platform.
+
+The running package determines the exact CLI version to install. The global executable is verified with `ae-cli --version`; PATH problems include the verified absolute path. Local npm links are protected by a small guard. Other installation conflicts use normal npm errors; the installer does not migrate existing installations.
+
+Skills are installed globally in `~/.agents/skills`. The shared files are installed once, then the Skills tool automatically distributes copies to detected clients that require their own directory. Shared-directory targets are skipped during distribution. Existing per-Skill links are replaced with copies when needed. Codex and Cursor support this shared directory, so installing Cursor later does not require a separate copy of the Skills. A client that only reads its own directory may need the same install command run again after that client is installed. User-global installation does not promise availability in remote/cloud clients or for every future client.
+
+The external tool is pinned to `skills@1.5.12` to preserve Node 20 support and skip copying a Skill onto its own source directory. The installer does not maintain its own Agent catalog, ask users to select clients, or select clients based on the invoking AI. Unrelated user Skills are retained.
+
+## Verification and output
+
+The installed CLI package's `skills/` directory defines the expected Skills and contents at runtime, including for historical packages without an installer or generated manifest. A failed shared-directory installation can retry the exact release tag `ThinkingAIAgenticEngine/ae-cli#v<CLI_VERSION>`; it never falls back to the default branch. Missing or invalid bundled Skills are reported rather than guessing the expected set from another version. Client distribution failures do not trigger a source download retry. If the local source and fallback both fail, the top-level error retains the first cause, and `skills.attempts` records both attempts with their stage, source, cause, and failures.
+
+Verification parses YAML/frontmatter and compares expected files in the shared global directory with the target package. Merely finding a directory, an `ae-*` name, or an exit code of zero is insufficient. Failures reported by the pinned tool for supported clients are also treated as failures, even when shared files exist.
+
+- Complete verification: `ok: true`.
+- Partial installation: `ok: false`, preserving the CLI result and listing failed Skills and reasons.
+- Unrelated PromptScript/Eve project-only diagnostics and their failure summary are handled internally and not displayed as user warnings after verification succeeds.
+- YAML errors, missing or stale files, supported-client installation errors, CLI version mismatch, and unsuccessful processes remain failures.
+
+`--format json` emits one report on stdout. Progress goes to stderr; raw subprocess logs are not forwarded. Reports include `ok`, `dry_run`, `cli.package/version/path/verified`, `skills.directory/expected_count/installed_count/missing/source/version/failures/attempts`, `auth.host/authenticated`, and `next_steps`. Counts refer to unique Skills in the global directory. Use `--format table` for a human summary. Dry runs make no subprocess calls or installation/configuration writes.
+
+## Host and login
+
+`--host` is optional. It delegates status checks to the existing auth command; it does not independently save credentials or change the active host. Being logged out does not make a verified installation fail.
+
+```bash
+ae-cli auth login --host <AE_HOST> --no-wait
+```
+
+Show the returned `verification_url` to the user. After browser authorization:
+
+```bash
+ae-cli auth login --host <AE_HOST> --device-code <DEVICE_CODE>
+ae-cli auth status --host <AE_HOST>
+```
+
+Never print, copy, or manually save any token.
+
+## Host-compatible upgrades and downgrades
+
+```bash
+ae-cli update --host <AE_HOST>
+ae-cli update --target 6.0.40 --dry-run
+```
+
+The target is the exact `aeCliVersion` returned by the host, not npm latest or the cluster's general product version. CLI and Skills follow that target together. Existing automatic synchronization eligibility, locking, retry limits, and pending-Skills recovery are retained. Automatic changes apply only to the public distribution, after login and during normal commands; help, version, auth, config, install, update, CI, and configured sandbox/skip modes do not initiate automatic synchronization.
+
+Host checks are cached for up to 24 hours. A cluster upgrade is discovered on a later eligible command after refresh, not by a background updater. Explicit `ae-cli update --host <AE_HOST>` queries immediately. A successful automatic switch asks the caller to rerun the original command.
+
+For example, a CLI with this installer can switch from 6.0.50 to an older 6.0.40 package using that package's bundled Skills. After the switch, the installed 6.0.40 CLI runs future updates with its own historical code; new validation and diagnostic handling do not survive the downgrade. The published 6.0.40 already has automatic upgrade/downgrade support, but invokes an unpinned Skills tool and does not perform this installer's complete verification. Successful version selection does not guarantee historical Skills tooling will work in every Node/network environment.
+
+To use the newer installer while still respecting the current host version, including to repair an older updater's failed Skills step:
+
+```bash
+npx @thinkingai/ae-cli@latest update --host <AE_HOST>
+```
+
+The newer command orchestrates the work; the installed target remains the host-required version. Required package versions and fallback tags must be published and accessible. Global CLI installation follows one target at a time; switching between differently versioned hosts can switch that installation again.
+
+## Advanced manual troubleshooting
+
+Prefer the unified installer. For a specific client or source diagnosis, advanced users can still invoke the external Skills tool directly:
+
+```bash
+npx -y skills@1.5.12 add <INSTALLED_CLI_SKILLS_PATH> -g -y --agent codex
+npx -y skills@1.5.12 list -g --json
+```
+
+Raw manual-tool output is not the AE installer's final result. Do not infer completeness from the list alone, delete unrelated Skills, or overwrite a source link to resolve a conflict.
+
+## AI installation prompt
+
+> Install AE CLI and its matching Skills globally. Check Node.js 20+, npm, and npx without changing my default Node version. Run `npx @thinkingai/ae-cli@latest install --format json`, adding `--host <AE_HOST>` only if I supplied a host. No Agent selection is needed. Judge success by the installer's final `ok`, CLI verification, and global Skills verification. The installer handles unrelated project-only client diagnostics internally. If installation fails, report the named Skills and reasons; do not hide YAML errors, missing files, or actual installation failures. Do not modify project files, delete unrelated Skills, use sudo, overwrite an npm source link, or print/copy/save tokens. After successful installation, guide me through device-code login if needed and wait for browser authorization. Then use `ae-cli update --host <AE_HOST>` to match the environment. If an older CLI cannot finish its update, use `npx @thinkingai/ae-cli@latest update --host <AE_HOST>` to retain exact host-version selection. Report the installed version, global Skills directory, verified Skill count, and authentication status.

package/dist/{auth-XZNXFRJS.js → auth-MBWRZTB6.js}

@@ -1,27 +1,27 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
-import {
-  MultiselectCancelled,
-  promptSingleSelect
-} from "./chunk-7K24F7T2.js";
 import {
   missingAeHostGuidance,
   missingAeHostHint
 } from "./chunk-6ZIQV5GW.js";
 import {
-  getLocalCliPackageInfo
-} from "./chunk-E2JKXMVO.js";
+  MultiselectCancelled,
+  promptSingleSelect
+} from "./chunk-7K24F7T2.js";
 import {
   resolveHost
-} from "./chunk-JOCDD4ON.js";
+} from "./chunk-7QXISROD.js";
 import {
+  getLocalCliPackageInfo,
   printError,
   printOutput,
   runHostCompatCheck
-} from "./chunk-DX5CDO34.js";
+} from "./chunk-KFNMQTZI.js";
 import {
   CliTokenValidationUnavailableError,
+  CredentialStoreUnreadableError,
   SecureStoreAuthError,
   activateCredential,
+  assertCredentialsReadable,
   clearAllCredentials,
   clearCliTokenCache,
   getActiveCredential,
@@ -31,17 +31,17 @@ import {
   saveCredential,
   updateCredentialMetadata,
   validateCliTokenOnServer
-} from "./chunk-7XGFSUOM.js";
+} from "./chunk-GIK6EDUG.js";
 import {
   getFallbackCliToken,
   loadConfig,
   normalizeUrl,
   saveConfig
-} from "./chunk-7FTTULED.js";
+} from "./chunk-UQ77JXYH.js";
 import {
   PermissionError,
   logger
-} from "./chunk-MAPZ7VB6.js";
+} from "./chunk-WNGFSIOB.js";
 
 // src/core/device-auth.ts
 import { execFileSync } from "child_process";
@@ -277,12 +277,77 @@ async function validateExistingCliToken(host, cliToken) {
       logger.warn(`auth status: ${error.message}; trusting the stored CLI token for compatibility`);
       return { valid: true, trusted: true, details: {} };
     }
+    if (error instanceof PermissionError) {
+      printError("permission", error.message, error.hint, error.code);
+      process.exitCode = 1;
+      return { valid: false, trusted: false, details: {} };
+    }
     if (!(error instanceof SecureStoreAuthError)) throw error;
-    printError("auth", error.message);
+    printError(
+      "auth",
+      error.message,
+      `Run: ae-cli auth logout --host ${host}, then ae-cli auth login --host ${host}`
+    );
     process.exitCode = 1;
     return { valid: false, trusted: false, details: {} };
   }
 }
+async function readCliTokenFromStdin() {
+  let value = "";
+  process.stdin.setEncoding("utf8");
+  for await (const chunk of process.stdin) value += chunk;
+  return value.trim();
+}
+function promptHiddenCliToken() {
+  const stdin = process.stdin;
+  const stderr = process.stderr;
+  if (!stdin.isTTY || !stderr.isTTY) {
+    return Promise.reject(new Error(
+      "Interactive CLI token input requires a TTY. Pipe the token and add --token-stdin."
+    ));
+  }
+  return new Promise((resolve, reject) => {
+    let value = "";
+    let settled = false;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    stderr.write("CLI token: ");
+    function cleanup() {
+      if (settled) return;
+      settled = true;
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.removeListener("data", onData);
+      stderr.write("\n");
+    }
+    function onData(chunk) {
+      for (const key of chunk) {
+        if (key === "\r" || key === "\n") {
+          cleanup();
+          resolve(value.trim());
+          return;
+        }
+        if (key === "" || key === "\x1B") {
+          cleanup();
+          reject(new Error("CLI token input cancelled."));
+          return;
+        }
+        if (key === "") {
+          cleanup();
+          resolve(value.trim());
+          return;
+        }
+        if (key === "\x7F" || key === "\b") {
+          value = value.slice(0, -1);
+          continue;
+        }
+        if (key >= " ") value += key;
+      }
+    }
+    stdin.on("data", onData);
+  });
+}
 function activateHostAfterLogin(host, explicitHostOverride) {
   if (!explicitHostOverride) return;
   const normalized = normalizeUrl(host);
@@ -369,11 +434,13 @@ async function switchActiveAccount(program, opts) {
       account: accountOutput(selected.account)
     }, program.opts().format || "json");
   } catch (error) {
+    if (error instanceof CredentialStoreUnreadableError) throw error;
     printError("auth", error.message);
     process.exitCode = 1;
   }
 }
 async function persistDeviceTokens(host, tokens, options = {}) {
+  assertCredentialsReadable(host);
   const cliToken = await mintCliToken(host, tokens.access_token);
   let validation = {};
   try {
@@ -401,6 +468,24 @@ async function persistDeviceTokens(host, tokens, options = {}) {
   await runHostCompatCheck(getLocalCliPackageInfo(), host);
   return saved;
 }
+async function persistManualCliToken(host, cliToken, options = {}) {
+  assertCredentialsReadable(host);
+  const validation = await validateCliTokenOnServer(host, cliToken);
+  let saved;
+  try {
+    saved = saveCredential(host, {
+      cliToken,
+      ...validation.account ? { account: validation.account } : {},
+      ...validation.cliTokenExpiresAt ? { cliTokenExpiresAt: validation.cliTokenExpiresAt } : {}
+    }, options);
+  } catch (error) {
+    clearCliTokenCache(host);
+    throw error;
+  }
+  clearCliTokenCache(host);
+  await runHostCompatCheck(getLocalCliPackageInfo(), host);
+  return saved;
+}
 function loginSummary(host, credential) {
   return {
     authenticated: true,
@@ -408,13 +493,30 @@ function loginSummary(host, credential) {
     ...credential.account ? { account: accountOutput(credential.account) } : {}
   };
 }
+function manualTokenSummary(host, credential) {
+  return {
+    authenticated: true,
+    host,
+    source: "manual-cli-token",
+    ...credential.account ? { account: accountOutput(credential.account) } : {},
+    cli_token: {
+      status: "valid",
+      ...credential.cliTokenExpiresAt ? { expires_at: credential.cliTokenExpiresAt } : {}
+    }
+  };
+}
 function resolveLoginTeClaudeBase(host) {
   const base = host.replace(/\/+$/, "");
   const basePath = process.env.TE_CLAUDE_BASE_PATH || "/agent";
   return base.endsWith(basePath) ? base : base + basePath;
 }
 function registerAuth(program) {
-  const auth = program.command("auth").description("Manage authentication or switch the active account interactively").action(async () => {
+  const auth = program.command("auth").description("Manage authentication or switch the active account interactively").hook("preAction", (_command, actionCommand) => {
+    if (["login", "set-token"].includes(actionCommand.name())) {
+      const host = resolveAuthHost(program, actionCommand.opts());
+      if (host) assertCredentialsReadable(host);
+    }
+  }).action(async () => {
     await switchActiveAccount(program, {});
   });
   auth.command("login").description("Log in to AE; by default replaces this host credentials, --add keeps existing accounts").option("--host <url>", HOST_OPTION_DESC).option("--add", "Add another account for the host and keep existing accounts").option("--no-browser", "Do not auto-open the browser; only print the authorization URL").option("--no-wait", "Print device authorization data and exit; resume with --device-code").option("--device-code <code>", "Resume a split-flow login with the given device code").action(async (opts) => {
@@ -465,6 +567,7 @@ function registerAuth(program) {
       emit("Login successful! CLI token saved securely.");
       await printOutput(loginSummary(host, saved), format);
     } catch (error) {
+      if (error instanceof CredentialStoreUnreadableError) throw error;
       if (error instanceof DeviceFlowUnsupportedError) {
         printError("auth", error.message, "Upgrade the AE server to a version that supports device login.");
         process.exit(1);
@@ -477,6 +580,59 @@ function registerAuth(program) {
       process.exit(1);
     }
   });
+  auth.command("set-token").description("Validate and securely store a CLI token copied from External Access Management").option("--host <url>", HOST_OPTION_DESC).option("--token-stdin", "Read the CLI token from stdin instead of prompting").option("--add", "Add another account for the host and keep existing accounts").action(async (opts) => {
+    const explicitHost = getExplicitAuthHostOverride(program, opts);
+    const host = resolveAuthHost(program, opts);
+    if (!host) {
+      printError("config", "No AE host configured.", missingAeHostHint());
+      process.exitCode = 1;
+      return;
+    }
+    let cliToken;
+    try {
+      cliToken = opts.tokenStdin ? await readCliTokenFromStdin() : await promptHiddenCliToken();
+    } catch (error) {
+      printError("validation", error.message);
+      process.exitCode = 1;
+      return;
+    }
+    if (!/^cli_\S+$/.test(cliToken)) {
+      printError(
+        "validation",
+        "Invalid CLI token format.",
+        "Copy a current CLI token from External Access Management; the value must start with cli_."
+      );
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      const saved = await persistManualCliToken(host, cliToken, { add: opts.add });
+      activateHostAfterLogin(host, explicitHost);
+      process.stderr.write(`[ae-cli] CLI token verified and saved securely for ${host}
+`);
+      await printOutput(manualTokenSummary(host, saved), program.opts().format || "json");
+    } catch (error) {
+      if (error instanceof CredentialStoreUnreadableError) throw error;
+      if (error instanceof PermissionError) {
+        printError("permission", error.message, error.hint, error.code);
+      } else if (error instanceof SecureStoreAuthError) {
+        printError(
+          "auth",
+          error.message,
+          "Copy a current CLI token from External Access Management and try again."
+        );
+      } else if (error instanceof CliTokenValidationUnavailableError) {
+        printError(
+          "api",
+          error.message,
+          "Verify the AE host and deployment, then retry. The token was not saved."
+        );
+      } else {
+        printError("api", error.message);
+      }
+      process.exitCode = 1;
+    }
+  });
   auth.command("status").description("Show the active CLI-token authentication status for a host").option("--host <url>", HOST_OPTION_DESC).action(async (opts) => {
     const host = resolveAuthHost(program, opts);
     if (!host) {
@@ -569,6 +725,8 @@ export {
   activateHostAfterLogin,
   buildAccountSelectionItems,
   persistDeviceTokens,
+  persistManualCliToken,
+  promptHiddenCliToken,
   registerAuth,
   resolveLoginTeClaudeBase
 };