@enter-pro/enter-cli 0.4.2 → 0.4.4

package/dist/commands/whoami.js

@@ -6,7 +6,7 @@ export const whoamiCmd = new Command("whoami")
     .description("Show current user info")
     .action(async (_opts, cmd) => {
     if (!isAuthenticated()) {
-        throw new Error("Not authenticated. Run `enter login` or set ENTER_API_KEY environment variable.");
+        throw new Error("Not authenticated. Run `enter-cli login` or set ENTER_API_KEY environment variable.");
     }
     const data = await client.get("/v1/users/info");
     const format = cmd.optsWithGlobals().output || "json";

package/dist/commands/workspace.js

@@ -1,12 +1,9 @@
 import { Command } from "commander";
 import * as client from "../client.js";
-import { print, printMessage, printTable, pickList } from "../output.js";
+import { print, printResult, printTable, pickList, getFormat } from "../output.js";
 export const workspaceCmd = new Command("workspace")
     .alias("ws")
     .description("Manage workspaces");
-function getFormat(cmd) {
-    return cmd.optsWithGlobals().output || "json";
-}
 workspaceCmd
     .command("list")
     .description("List workspaces")
@@ -68,9 +65,9 @@ workspaceCmd
 workspaceCmd
     .command("delete <workspace_id>")
     .description("Delete a workspace")
-    .action(async (id) => {
+    .action(async (id, _opts, cmd) => {
     await client.del(`/v1/workspaces/${id}`);
-    printMessage("Workspace deleted successfully.");
+    printResult(getFormat(cmd), { deleted: true, workspace_id: id }, "Workspace deleted successfully.");
 });
 // Members subcommand group
 const membersCmd = new Command("members").description("Manage workspace members");
@@ -118,7 +115,7 @@ membersCmd
     .description("Remove a member from workspace")
     .option("--email <email>", "Member email")
     .option("--user-id <id>", "Member user ID")
-    .action(async (id, opts) => {
+    .action(async (id, opts, cmd) => {
     if (!opts.email && !opts.userId) {
         throw new Error("--email or --user-id is required");
     }
@@ -128,7 +125,7 @@ membersCmd
     if (opts.userId)
         body.user_id = Number(opts.userId);
     await client.post(`/v1/workspaces/${id}/members/remove`, body);
-    printMessage("Member removed successfully.");
+    printResult(getFormat(cmd), { removed: true, workspace_id: id }, "Member removed successfully.");
 });
 membersCmd
     .command("update-role <workspace_id>")
@@ -155,9 +152,9 @@ membersCmd
 membersCmd
     .command("leave <workspace_id>")
     .description("Leave a workspace")
-    .action(async (id) => {
+    .action(async (id, _opts, cmd) => {
     await client.post(`/v1/workspaces/${id}/leave`);
-    printMessage("Left workspace successfully.");
+    printResult(getFormat(cmd), { left: true, workspace_id: id }, "Left workspace successfully.");
 });
 workspaceCmd.addCommand(membersCmd);
 // Credits subcommand group

package/dist/config.d.ts

@@ -2,7 +2,6 @@ export interface Config {
     api_url: string;
     base_path: string;
     output: string;
-    default_workspace: string;
 }
 export declare function configDir(): string;
 export declare function loadConfig(): Config;

package/dist/config.js

@@ -8,7 +8,6 @@ const defaults = {
     api_url: "https://api.enter.pro",
     base_path: "/code/api",
     output: "json",
-    default_workspace: "",
 };
 function ensureConfigDir() {
     if (!existsSync(CONFIG_DIR)) {
@@ -32,8 +31,6 @@ function getEnvOverrides() {
         overrides.base_path = process.env.ENTER_BASE_PATH;
     if (process.env.ENTER_OUTPUT)
         overrides.output = process.env.ENTER_OUTPUT;
-    if (process.env.ENTER_DEFAULT_WORKSPACE)
-        overrides.default_workspace = process.env.ENTER_DEFAULT_WORKSPACE;
     return overrides;
 }
 export function configDir() {
@@ -42,15 +39,24 @@ export function configDir() {
 export function loadConfig() {
     const fileConfig = loadFromFile();
     const envOverrides = getEnvOverrides();
-    return { ...defaults, ...fileConfig, ...envOverrides };
+    const merged = { ...defaults, ...fileConfig, ...envOverrides };
+    return Object.fromEntries(Object.keys(defaults).map(key => [key, merged[key]]));
 }
 export function setConfig(key, value) {
+    validateKey(key);
+    if (key === "output" && !["json", "yaml", "table"].includes(value))
+        throw new Error("output must be json, yaml or table");
     ensureConfigDir();
     const current = loadFromFile();
     current[key] = value;
     writeFileSync(CONFIG_FILE, yaml.dump(current), "utf-8");
 }
+function validateKey(key) {
+    if (!Object.hasOwn(defaults, key))
+        throw new Error(`Unsupported setting "${key}". Supported settings: ${Object.keys(defaults).join(", ")}. Pass workspace IDs explicitly to project commands.`);
+}
 export function getConfig(key) {
+    validateKey(key);
     const cfg = loadConfig();
     return cfg[key] || "";
 }

package/dist/output.d.ts

@@ -6,21 +6,5 @@ export declare function printMessage(msg: string): void;
 export declare function printResult(format: string, structured: unknown, message: string): void;
 import type { Command } from "commander";
 export declare function getFormat(cmd: Command): string;
-export declare function printError(err: Error | string): void;
 export declare function pick<T extends Record<string, unknown>>(obj: T, keys: string[]): Record<string, unknown>;
 export declare function pickList(items: Record<string, unknown>[], keys: string[]): Record<string, unknown>[];
-export interface ListEnvelope {
-    items: unknown[];
-    total?: number;
-    page?: number;
-    page_size?: number;
-}
-export interface TableConfig {
-    headers: string[];
-    rowMapper: (item: Record<string, unknown>) => string[];
-}
-export declare function printList(format: string, data: ListEnvelope, tableConfig?: TableConfig): void;
-export declare function printSingle(format: string, data: unknown, tableConfig?: {
-    headers: string[];
-    rowMapper: (item: Record<string, unknown>) => string[];
-}): void;

package/dist/output.js

@@ -59,9 +59,6 @@ export function printResult(format, structured, message) {
 export function getFormat(cmd) {
     return cmd.optsWithGlobals().output || "json";
 }
-export function printError(err) {
-    console.error(`Error: ${typeof err === "string" ? err : err.message}`);
-}
 export function pick(obj, keys) {
     const result = {};
     for (const key of keys) {
@@ -72,18 +69,3 @@ export function pick(obj, keys) {
 export function pickList(items, keys) {
     return items.map((item) => pick(item, keys));
 }
-export function printList(format, data, tableConfig) {
-    if (format === "table" && tableConfig) {
-        const rows = data.items.map(tableConfig.rowMapper);
-        printTable(tableConfig.headers, rows);
-        return;
-    }
-    print(format, data);
-}
-export function printSingle(format, data, tableConfig) {
-    if (format === "table" && tableConfig) {
-        printTable(tableConfig.headers, [tableConfig.rowMapper(data)]);
-        return;
-    }
-    print(format, data);
-}

package/dist/poll.d.ts

@@ -2,6 +2,7 @@ export declare class TimeoutError extends Error {
     constructor(elapsedMs: number);
 }
 export interface PollOptions {
+    signal?: AbortSignal;
     intervalMs?: number;
     timeoutMs?: number;
     onTick?: (elapsed: number, data: unknown) => void;

package/dist/poll.js

@@ -1,3 +1,4 @@
+import { setTimeout as delay } from "node:timers/promises";
 export class TimeoutError extends Error {
     constructor(elapsedMs) {
         super(`Timed out after ${Math.round(elapsedMs / 1000)}s`);
@@ -10,6 +11,7 @@ export async function pollUntil(fetcher, predicate, options) {
     const onTick = options?.onTick;
     const start = Date.now();
     while (true) {
+        options?.signal?.throwIfAborted();
         const data = await fetcher();
         const elapsed = Date.now() - start;
         if (predicate(data)) {
@@ -19,6 +21,6 @@ export async function pollUntil(fetcher, predicate, options) {
             throw new TimeoutError(elapsed);
         }
         onTick?.(elapsed, data);
-        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        await delay(Math.min(intervalMs, Math.max(0, timeoutMs - elapsed)), undefined, { signal: options?.signal });
     }
 }

package/dist/thread-events.d.ts

@@ -30,6 +30,7 @@ export declare class ThreadEvents {
     private wake;
     private setMode;
     private connect;
+    private connectAuthenticated;
     wait(afterRevision: number, timeoutMs: number): Promise<void>;
     close(): void;
 }

package/dist/thread-events.js

@@ -2,7 +2,7 @@ import WebSocket from "ws";
 import { HttpsProxyAgent } from "https-proxy-agent";
 import { getProxyForUrl } from "proxy-from-env";
 import { baseURL } from "./config.js";
-import { getToken } from "./auth.js";
+import { getValidToken } from "./auth.js";
 import { RequestError } from "./errors.js";
 export function streamURL(base, projectId, options) {
     const url = new URL(`${base.replace(/\/$/, "")}/v1/projects/${encodeURIComponent(projectId)}/thread/stream`);
@@ -77,10 +77,20 @@ export class ThreadEvents {
         this.wake();
     }
     connect() {
+        void this.connectAuthenticated().catch(error => {
+            if (this.stopped)
+                return;
+            this.failure = new RequestError("STREAM_SETUP_ERROR", error instanceof Error ? error.message : "Could not initialize Enter event stream.");
+            this.setMode("polling", "stream_setup_failed");
+        });
+    }
+    async connectAuthenticated() {
         if (this.stopped)
             return;
         const url = streamURL(baseURL(), this.projectId, { ...this.options, cursor: this.cursor });
-        const token = getToken();
+        const token = await getValidToken(this.options.signal);
+        if (this.stopped)
+            return;
         // proxy-from-env honors NO_PROXY, including loopback fixture servers.
         const proxy = process.env.NODE_USE_ENV_PROXY === "0" ? "" : getProxyForUrl(url.toString().replace(/^ws/, "http"));
         const socket = new WebSocket(url, {
@@ -100,7 +110,10 @@ export class ThreadEvents {
             if ([401, 403].includes(status)) {
                 retryable = false;
                 reason = status === 401 ? "authentication_required" : "permission_denied";
-                this.failure = new RequestError("STREAM_AUTH_ERROR", "Enter event stream rejected access. Check authentication and project permissions.");
+                // State observers retain authoritative HTTP polling; raw message followers cannot.
+                if (!this.options.stateOnly) {
+                    this.failure = new RequestError("STREAM_AUTH_ERROR", "Enter event stream rejected access. Check authentication and project permissions.");
+                }
             }
             else if ([404, 405, 426, 501].includes(status)) {
                 retryable = false;

package/dist/workflow.d.ts

@@ -0,0 +1,46 @@
+export type ThreadStatus = 'idle' | 'running' | 'queued' | 'pending' | 'blocked' | 'completed' | 'failed' | 'unknown';
+export type InputKind = 'none' | 'secret' | 'questions' | 'auth_provider';
+export interface WorkflowSnapshot {
+    status: ThreadStatus;
+    task_id?: unknown;
+    turn?: Record<string, unknown> | null;
+    actions?: Record<string, unknown>[];
+    project?: Record<string, unknown>;
+    reason?: string;
+    interrupted?: boolean;
+    wait_timed_out?: boolean;
+    observation_retrying?: boolean;
+    progress_changed?: boolean;
+    error?: {
+        retryable?: boolean;
+    };
+}
+/** Host-facing workflow decisions, independent of transport and backend phases. */
+export declare function workflowResult(snapshot: WorkflowSnapshot): {
+    actions?: {
+        id: unknown;
+        kind: unknown;
+        decision: string;
+        required_fields: {};
+        submit_command: unknown;
+    }[] | undefined;
+    build?: {
+        commit: {} | null;
+        matches_task: boolean;
+        success: {} | null;
+    } | undefined;
+    observation: {
+        timed_out: boolean;
+        retrying: boolean;
+        interrupted: boolean;
+    };
+    reason?: string | undefined;
+    after_reporting?: string | undefined;
+    state: string;
+    task: {
+        id: {} | null;
+        turn: {} | null;
+        chat_id: {} | null;
+    };
+    next_action: string;
+};

package/dist/workflow.js

@@ -0,0 +1,36 @@
+/** Host-facing workflow decisions, independent of transport and backend phases. */
+export function workflowResult(snapshot) {
+    const turn = snapshot.turn;
+    const actions = snapshot.actions ?? [];
+    const build = snapshot.project?.build_status;
+    const state = snapshot.status === 'blocked' ? 'needs_input'
+        : snapshot.status === 'queued' || snapshot.status === 'pending' ? 'running' : snapshot.status;
+    const next = snapshot.interrupted ? 'resume_when_requested'
+        : snapshot.error && !snapshot.error.retryable ? 'resolve_error'
+            : state === 'needs_input' ? 'handle_actions'
+                : state === 'completed' ? 'read_delivery'
+                    : state === 'failed' ? 'report_failure'
+                        : snapshot.progress_changed ? 'report_progress'
+                            : state === 'idle' ? 'none'
+                                : 'observe';
+    return {
+        state,
+        task: { id: snapshot.task_id ?? turn?.task_id ?? turn?.id ?? null, turn: turn?.turn ?? null, chat_id: turn?.chat_id ?? null },
+        next_action: next,
+        ...(next === "report_progress" ? { after_reporting: "observe" } : {}),
+        ...(snapshot.reason ? { reason: snapshot.reason } : {}),
+        observation: { timed_out: Boolean(snapshot.wait_timed_out), retrying: Boolean(snapshot.observation_retrying), interrupted: Boolean(snapshot.interrupted) },
+        ...(snapshot.project ? { build: {
+                commit: build?.commit_id ?? null,
+                matches_task: Boolean(turn?.commit_id && build?.commit_id === turn.commit_id),
+                success: build?.success ?? null,
+            } } : {}),
+        ...(actions.length ? { actions: actions.map(action => ({
+                id: action.action_id,
+                kind: action.tool_name === 'confirm_plan_mode' ? 'plan' : action.input_kind === 'none' ? 'confirmation' : action.input_kind,
+                decision: action.tool_name === 'confirm_plan_mode' || action.input_kind === 'questions' ? 'ask_user' : 'use_existing_authorization',
+                required_fields: action.configuration?.fields ?? (action.input_kind === 'secret' ? (action.tool_name === 'supabase_add_secret' ? ['secret_name', 'secret_value'] : ['secret_value']) : []),
+                submit_command: action.approve_command,
+            })) } : {}),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enter-pro/enter-cli",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Enter CLI - manage Enter platform resources from the command line",
   "type": "module",
   "main": "dist/index.js",
@@ -14,10 +14,14 @@
     "test": "npm run build && node --test",
     "mock:serve": "node scripts/mock-enter.mjs",
     "local:cli": "node scripts/local-cli.mjs",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "install:hosts": "node scripts/install-hosts.mjs"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "scripts/install-hosts.mjs",
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"

package/scripts/install-hosts.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync, mkdirSync, cpSync, chmodSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve, join } from 'node:path';
+import { createHash } from 'node:crypto';
+const { values } = parseArgs({ options: { package: { type: 'string' }, host: { type: 'string', default: 'all' }, home: { type: 'string', default: homedir() } } });
+if (!values.package || !['all', 'codex', 'dsh'].includes(values.host)) throw Error('Usage: install-hosts.mjs --package /path/package.tgz [--host all|codex|dsh] [--home /path]');
+const archive = realpathSync(values.package);
+const hash = createHash('sha256').update(readFileSync(archive)).digest('hex');
+const quote = s => "'" + s.replaceAll("'", "'\\''") + "'";
+for (const host of values.host === 'all' ? ['codex', 'dsh'] : [values.host]) {
+  const root = join(resolve(values.home), '.' + host);
+  const prefix = join(root, 'tools/enter-cli');
+  const result = spawnSync('npm', ['install', '--prefix', prefix, '--ignore-scripts', '--no-audit', '--no-fund', archive], { stdio: 'inherit' });
+  if (result.status !== 0) throw Error(`Installation failed for ${host}`);
+  const installed = join(prefix, 'node_modules/@enter-pro/enter-cli');
+  const skill = join(root, 'skills/enter');
+  mkdirSync(join(skill, 'scripts'), { recursive: true });
+  cpSync(join(installed, 'skills/enter/references'), join(skill, 'references'), { recursive: true });
+  const wrapper = join(skill, 'scripts/enter-cli');
+  writeFileSync(wrapper, '#!/bin/sh\nset -eu\nexport NODE_USE_ENV_PROXY="${NODE_USE_ENV_PROXY:-1}"\nexec ' + quote(realpathSync(process.execPath)) + ' ' + quote(join(installed, 'dist/index.js')) + ' "$@"\n');
+  chmodSync(wrapper, 0o755);
+  writeFileSync(join(skill, 'SKILL.md'), readFileSync(join(installed, 'skills/enter/SKILL.md'), 'utf8').replaceAll('{{CLI_ENTRY}}', wrapper));
+  const pkg = JSON.parse(readFileSync(join(installed, 'package.json'), 'utf8'));
+  writeFileSync(join(prefix, 'install-info.json'), JSON.stringify({ version: pkg.version, package_sha256: hash, installed_at: new Date().toISOString(), source_archive: archive }, null, 2) + '\n');
+  console.log(`${host}: installed ${pkg.version}, sha256 ${hash}`);
+}

package/skills/enter/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: enter
+description: 使用 Enter CLI 创建和修改网站或应用，跟踪任务、处理提问与配置卡，并交付 Enter 的构建和验证结果。
+---
+
+# Enter
+
+用户描述需求，Enter 负责开发与视觉/功能验证，宿主通过 CLI 提交、收集输入和交付。
+
+## 入口
+
+使用 `{{CLI_ENTRY}}`。第一次调用核对 `--version` 和登录状态；命令参数按需查 `--help`。输出优先用 JSON，保持 stdout/stderr 分离；不要回显完整身份资料或凭据。
+
+## 流程
+
+1. 从用户上下文确定项目；新建时确定 workspace。通过 `project create` 或 `thread chat` 提交一次，保存 task_id。accepted 或观察超时不代表完成，也不是重新提交的理由。
+2. 按下方宿主能力规则选择返回的 stream_command 或 wait_command，按同一 task_id 继续；需交付构建时加 `--require-build`。新增需求单独记录返回的 task_id。
+3. 状态的 `workflow` 给出任务关联、next_action 和构建匹配信息。遇到 `handle_actions` 按下方卡片规则处理；`read_delivery` 执行 messages_command，取得 Enter 的总结与验证证据。未知关联不代表提交失败，不猜测它属于其他已完成任务。
+4. 依用户已有授权继续，不因阶段切换反复确认。明确要求用户决策的计划和提问仍需转交。写操作超时或解析失败先查真实状态，再决定是否重试。
+5. 交付说明完成内容、预览/发布地址、Enter 验证结果及待配置项；代码存在、配置保存、构建成功、真实服务可用分开判断。发布按用户授权范围执行。
+
+## 观察与响应
+
+- CLI 用 HTTP 获取真实状态与 Enter 最新进度原文。宿主作为传话者：`workflow.next_action=report_progress` 时先转述 `progress.messages`，再按 `after_reporting=observe` 续接；处理其他 `workflow.next_action`，执行返回的命令；不翻原始日志自行分析开发阶段，不把 Enter 的自述当独立验收。`progress.available=false` 表示暂时无法获取进度，不能说没有进展；有数据但 revision 未变才是没有新内容。不编造百分比，不用额度消耗、时间戳变化证明进展。默认只读取监控字段，除非用户查询详情，不使用 --full。
+- 首选单个 `stream_command`（`thread wait --stream --timeout 0`）：仅在宿主支持后台执行、增量输出通知和同时处理用户消息时使用。CLI 内部轮询，宿主非阻塞消费阶段性事件；运行期间不要另起 wait，不因 report_progress 重启观察。收到最终 result 后再按状态处理；不使用 shell & 脱离宿主管理。watch 保留为同一流式观察能力的兼容入口。
+- 同步或仅有完成通知的宿主回退到 `wait_command`：它在普通进度合并窗口到达且有新进展时退出，所以只支持任务完成通知的后台宿主，也能被新进展唤醒。支持后台任务时在后台运行并用完成通知续接，不阻塞等整个网站完成；同步宿主直接执行有界 wait。
+- `wait` 返回 `progress_changed=true` 时直接简短转述，再执行带 `--after-progress` 的续接命令。只有确认宿主能在新 stdout 到达时唤醒 Agent，才选择 `watch_command`；仅能手动读取运行中输出还不够。不得用反复 job_output 空读替代通知，也不得阻塞读取直到后台任务结束。watch 无限观察仅显式 `--timeout 0`。
+- 按 CLI 合并后的进展简短汇报；细碎技术变化无需逐条复述。面向用户不解释 CLI 协议、job 状态或调度过程。相同 revision、heartbeat 和无变化超时无需重复刷屏。超时结束的是本次观察，不是远端工作。保持同一 task_id、turn、chat 和构建要求，不重提、不询问是否继续，不写 sleep 或 status 循环。
+- 用户插话时立即用最近已知的进度与 `observed_at` 回答，标明是上次观察；之后按需刷新一次 status，再继续原任务。不要为了拿最新状态先阻塞回答。新增需求才提交 chat，单纯问进度不触发构建。
+- 普通进度默认每 10 秒合并一次（`--progress-interval`），保留最新原文，不猜测阶段；问题卡、完成和失败立即返回。保留返回的间隔与时限，不自行调长等待。
+- `wait` 默认最多 10 秒，`watch` 默认 60 秒，显式时限会保留在续接命令中。这是观察上限，不是心跳周期或响应保证；不得为等到完成不断延长阻塞调用。宿主如果本身不支持插话或后台唤醒，CLI 不能保证即时响应或主动通知。
+
+## 卡片
+
+- 计划：展示 plan，等待用户同意或修改意见，展示不等于批准。
+- ask_user_question：转交所有问题、选项和单/多选要求，收集答案后用 --answers 回传。JSON 的键是 Enter 原始问题全文，不是宿主提问工具生成的 ID；值是 {"selected_options":["选项原文"],"other_text":"自由文字"}，纯文字回答使用空数组。只有用户要求跳过时才执行 skip_command。
+- 普通确认：已有授权就 approve；需要新的决定时询问。用户拒绝才 reject。
+- 配置输入：已有授权和值/文件就提交；缺什么只问什么。普通配置可直接询问，真实密钥使用可用的安全输入或用户指定文件；表单是替代入口，不强制绕路。OAuth/secret/Stripe 的字段、stdin 和更新方法见 [配置输入](references/configuration.md)，仅遇到这些卡片时读取。
+
+CLI 负责 HTTP 观察和可选的事件监听；宿主负责后台调度与用户交互。等待工具不自动批准卡片。宿主没有浏览器不影响 Enter 内部验证，不以关键词扫描替代其验证结果。

package/skills/enter/references/configuration.md

@@ -0,0 +1,19 @@
+# 配置输入
+
+遇到 OAuth、Stripe 或 secret 卡时读取。目标是让用户提供一次所缺信息，然后由 CLI 保存、批准并继续任务。
+
+1. 读取卡片字段和现有任务上下文。已有获授权的值或文件直接使用；缺少字段时只说明字段用途及可用输入方式，不默认要求切换网页，也不反复确认已有授权。
+2. 非敏感配置（例如 GA Measurement ID）可直接询问。真实密钥使用宿主已有安全输入或用户指定文件；没有这些渠道时给出 Enter 项目表单入口。不要虚构宿主弹窗。用户主动提供的值可按当前授权处理，避免再次复制；若工具无法在不暴露值的情况下提交，说明具体限制并改用文件或表单。
+3. OAuth JSON 字段以卡片 configuration.fields 为准。Google 示例结构为 client_ids、client_secret；只在确实需要时给模板。文件通过重定向送入 stdin，命令中只有路径：
+
+```sh
+<CLI> --output json thread approve <PROJECT> <ACTION> --auth-config-stdin < /absolute/path/oauth.json
+<CLI> --output json thread approve <PROJECT> <ACTION> --secret-value-stdin < /absolute/path/stripe-key.txt
+<CLI> --output json thread approve <PROJECT> <ACTION> --secret-name <NAME> --secret-value-stdin < /absolute/path/secret.txt
+```
+
+`<CLI>` 使用技能入口的实际路径。不要 cat 文件、把值插入 printf/heredoc 或复制进 Enter 构建提示；这些都会进入工具记录。stdin 只避免 CLI 参数暴露，不能消除上游聊天或工具记录。不要在命令中合并 stderr 与需要 JSON 解析的 stdout。
+
+4. 表单保存可能已批准卡片，先查状态；CLI 批准后按返回 task_id 继续。不重复要求用户填写。OAuth 回调地址以实际配置返回或表单为准；需要服务商配置时提供确切地址，不猜测，也不声称该地址只能从某个入口取得。
+5. 提交失败先查状态再决定是否重试；例如 failed to connect Stripe 只说明连接失败，未证明具体原因。缺输入时等待补填，不自行拒绝卡片。用户明确暂不接入才 reject。
+6. 读取 Enter 的交付总结和验证证据。分别说明配置已保存、功能已接线、构建/发布状态、真实服务是否验证；mock 值可以验证流程，不能证明登录或支付成功。需要换值时沿同一配置流程更新，保持用户已选择的发布范围。