@steercards/agent-tools 0.1.1 → 0.1.3

package/CONTRIBUTING.md

@@ -25,7 +25,7 @@ npm pack --dry-run
 - `serve`의 stdout은 MCP 메시지 전용입니다. 진단 로그는 stderr로 출력하고 키를 노출하지 않습니다.
 - `setup`은 MCP 설정과 Skill을 함께 설치·업데이트합니다. Steercards 외 설정·주석·사용자 파일은 보존하고 관리 항목에 사용자 수정이 있으면 쓰기 전에 중단합니다. 임시 프로젝트와 격리한 홈 디렉터리에서 첫 설치, 재실행, 이전 버전 업데이트, 충돌, dry run과 쓰기 실패 복구를 검증하세요.
 - `.steercards/setup/` 기록의 버전·옵션·해시를 다음 업데이트의 기준으로 사용합니다. 실제 개인 설치 기록과 ZIP은 테스트 fixture나 커밋에 넣지 마세요.
-- `setup`은 키 없이 실행하고 `.env`를 생성·변경하지 않습니다. `config`는 설정 조각만 출력하며 개별 `skill install`은 사용자 수정 파일을 덮어쓰지 않습니다.
+- 코드 옵션 없는 `setup`은 키 없이 실행하고 `.env`를 변경하지 않습니다. 일회용 코드 모드에서는 로컬 충돌·추적·쓰기 점검을 교환 전에 완료하고, 저장 뒤 설치 실패 시 `.env`를 보존합니다. HTTP fixture와 packed bin/npx·Windows stdin 검사에서 코드·키 비노출 및 재교환 금지를 확인하세요. `config`는 설정 조각만 출력하며 개별 `skill install`은 사용자 수정 파일을 덮어쓰지 않습니다.
 
 변경 제안은 [공개 저장소](https://github.com/velody-ai/steercards-agent-tools)에 PR로 올려주세요. 보안 문제는 공개 이슈에 올리지 말고 [SECURITY.md](SECURITY.md)를 따릅니다.
 

package/README.md

@@ -9,6 +9,34 @@ Steercards의 전체 MCP 도구를 CLI와 에이전트에서 사용할 수 있
 
 패키지 이름은 `@steercards/agent-tools`, 실행 명령은 `steercards`입니다. npm에서 설치하거나 소스에서 빌드해 사용할 수 있습니다.
 
+## 일회용 프롬프트로 연결
+
+Steercards의 Agent 연결 화면에서 클라이언트·OS·Key 설정을 선택하고 설치 프롬프트를 복사해 사용할 프로젝트의 에이전트에게 전달하세요. 프롬프트에는 10분 동안 한 번 사용할 설치 코드가 들어갑니다. 설치기는 코드를 실제 Agent Key로 교환하여 현재 프로젝트의 `.env`에만 저장하고, `.gitignore` 보호·MCP 설정·Skill 설치와 읽기 전용 연결 검사를 수행합니다. 장기 키를 프롬프트에 붙여넣을 필요가 없습니다.
+
+직접 실행하는 경우 아래 코드 자리를 앱에서 발급한 설치 코드로 바꿉니다. POSIX 셸 예시:
+
+```sh
+npx -y -- @steercards/agent-tools@latest setup --client codex-app --cwd . --env-file .env --url https://steercards.com/api/mcp --setup-code-stdin <<'STEERCARDS_SETUP_CODE'
+<일회용 설치 코드>
+STEERCARDS_SETUP_CODE
+```
+
+Windows PowerShell에서는 같은 코드를 here-string으로 전달합니다.
+
+```powershell
+@'
+<일회용 설치 코드>
+'@ | npx -y -- @steercards/agent-tools@latest setup --client codex-app --cwd . --env-file .env --url https://steercards.com/api/mcp --setup-code-stdin
+```
+
+`--cwd .`는 실행한 현재 프로젝트를 뜻하며 생략해도 같습니다. `--client`는 선택한 클라이언트로 바꾸고, 다른 서버를 사용한다면 그 서버의 MCP URL을 명시하세요. 설치 코드와 발급된 키는 명령 인자·출력·설치 기록에 넣지 않습니다. 자동 연결 검사는 호출 프로세스의 다른 키보다 저장한 `.env`의 키를 사용합니다.
+
+기존 `.env`의 다른 값·주석·개행을 보존합니다. 이미 Agent Key가 있으면 그대로 사용하고 코드를 교환하지 않습니다. 교체하려면 같은 setup 명령에 `--replace-agent-key`를 명시하세요. 이전 키를 서버에서 자동 폐기하지는 않습니다. 자동 쓰기는 프로젝트 루트 `.env`만 지원합니다. 이전 설치가 다른 env 파일을 참조하면 교환 전에 중단하므로 `--env-file .env`로 전환을 명시합니다.
+
+`.env`가 Git에 추적되거나 파일·설정·Skill 충돌, symlink, 잠금·쓰기 문제가 있으면 교환 전에 중단합니다. `.gitignore`의 기존 negation 뒤에 보호 규칙을 보완합니다. `--dry-run`은 코드를 소비하거나 파일을 쓰지 않습니다.
+
+키 저장 뒤 MCP·Skill 설치나 연결 검사에 실패해도 `.env`를 보존합니다. 충돌을 정리하고 코드 옵션 없이 일반 setup과 `doctor --connect`를 다시 실행하세요. 교환 응답 유실이나 키 저장 실패는 코드가 소비되었을 수 있으므로 앱에서 새 코드를 발급하고 사용하지 않는 발급 키를 폐기합니다. 실패 복구를 위해 키 원문을 채팅·로그에 붙여넣지 마세요. Desktop의 Skill ZIP 업로드와 클라이언트 재연결은 아래 안내를 따릅니다.
+
 ## 소스에서 설치
 
 소스 디렉터리에서 빌드한 뒤 `setup --local`을 실행합니다.
@@ -16,10 +44,10 @@ Steercards의 전체 MCP 도구를 CLI와 에이전트에서 사용할 수 있
 ```sh
 npm ci
 npm run build
-node /absolute/path/agent-tools/dist/cli.js setup --client codex-app --cwd /absolute/path/project --local
+node -- /absolute/path/agent-tools/dist/cli.js setup --client codex-app --cwd /absolute/path/project --local
 ```
 
-`setup` 한 번으로 Steercards MCP 설정과 Skill을 함께 설치합니다. 키 없이 설치할 수 있으며 `.env`를 만들거나 덮어쓰지 않습니다. 설치 뒤 프로젝트에 `.env.example`을 참고한 `.env`를 만들고 실제 Agent Key를 입력하세요.
+코드 옵션 없는 `setup`은 Steercards MCP 설정과 Skill을 키 없이 설치하며 `.env`를 변경하지 않습니다. 수동 연결에서는 설치 뒤 프로젝트에 `.env.example`을 참고한 `.env`를 만들고 실제 Agent Key를 입력하세요.
 
 ```dotenv
 STEERCARDS_AGENT_KEY=your-agent-key
@@ -32,7 +60,7 @@ STEERCARDS_MCP_URL=https://steercards.com/api/mcp
 클라이언트에서 필요한 MCP 승인과 재시작·다시 연결을 마친 뒤 확인합니다.
 
 ```sh
-node /absolute/path/agent-tools/dist/cli.js doctor --cwd /absolute/path/project --connect
+node -- /absolute/path/agent-tools/dist/cli.js doctor --cwd /absolute/path/project --connect
 ```
 
 `doctor`는 키 값을 출력하지 않습니다. `--connect`를 추가하면 원격 서버에 연결하고 워크스페이스 목록을 조회하는 읽기 전용 검사를 수행합니다. 생략하면 로컬 설정만 확인합니다.
@@ -42,7 +70,7 @@ node /absolute/path/agent-tools/dist/cli.js doctor --cwd /absolute/path/project
 처음 설치할 때와 새 버전으로 업데이트할 때 같은 명령을 사용합니다.
 
 ```sh
-npx -y @steercards/agent-tools@latest setup --client codex-app --cwd /absolute/path/project
+npx -y -- @steercards/agent-tools@latest setup --client codex-app --cwd /absolute/path/project
 ```
 
 실행한 패키지 버전의 MCP 설정과 Skill을 함께 적용합니다. npx 기반 MCP 실행 명령은 해당 버전에 고정되므로 Skill과 같은 버전을 사용합니다. 같은 버전·옵션으로 다시 실행하면 변경 없이 성공합니다. 기존 설치에서는 생략한 실행 옵션(`--local`, `--mode`, `--url`, `--env-file`)을 설치 기록에서 유지합니다. `--local` 설치는 새 소스를 받은 뒤 `npm ci`, `npm run build`를 실행하고 같은 `setup --local` 명령을 다시 실행하세요.
@@ -50,7 +78,7 @@ npx -y @steercards/agent-tools@latest setup --client codex-app --cwd /absolute/p
 소스의 `--local` 설치를 npm 실행 방식으로 전환할 때는 `--npx`를 지정합니다. 이후 MCP 설정은 실행한 패키지 버전의 npx 명령을 사용합니다.
 
 ```sh
-npx -y @steercards/agent-tools@latest setup --client codex-app --cwd /absolute/path/project --npx
+npx -y -- @steercards/agent-tools@latest setup --client codex-app --cwd /absolute/path/project --npx
 ```
 
 전역 설치를 선택했다면 패키지를 업데이트한 뒤 `setup`을 다시 실행합니다.
@@ -60,7 +88,7 @@ npm install --global @steercards/agent-tools@latest
 steercards setup --client codex-app --cwd /absolute/path/project
 ```
 
-이하 `steercards` 명령은 전역 설치를 기준으로 합니다. 소스 빌드 사용자는 `node /absolute/path/agent-tools/dist/cli.js`로 대체하면 됩니다.
+이하 `steercards` 명령은 전역 설치를 기준으로 합니다. 소스 빌드 사용자는 `node -- /absolute/path/agent-tools/dist/cli.js`로 대체하면 됩니다.
 
 ## 환경 설정
 
@@ -74,6 +102,15 @@ steercards setup --client codex-app --cwd /absolute/path/project
 
 이미 설정된 프로세스 환경 변수가 `.env`보다 우선합니다. 기본 `.env`는 지정한 디렉터리에서만 찾으며 상위 디렉터리를 탐색하지 않습니다. dotenv 값에 셸 명령이나 `${VARIABLE}` 확장을 수행하지 않습니다. 원격 URL은 HTTPS를 사용하며 로컬 개발용 loopback 주소만 HTTP를 허용합니다. URL의 인증 정보·쿼리·fragment는 허용하지 않습니다.
 
+프로젝트 밖에서도 상대 파일을 선택할 수 있습니다.
+
+```sh
+steercards doctor --cwd /absolute/path/project --env-file alternate.env
+npx -y -- @steercards/agent-tools@latest doctor --cwd /absolute/path/project --env-file alternate.env
+```
+
+`npx`에서는 패키지 이름 앞의 `--`를 유지하세요. Node 22 일부 버전은 프로그램 뒤의 `--env-file`도 시작 전에 검사하므로 이 경계가 필요합니다. 직접 Node로 실행할 때도 위 예시처럼 스크립트 경로 앞에 `--`를 넣습니다. 설치된 `steercards`와 새로 생성한 MCP 설정은 이 경계를 포함합니다. 기존 MCP 설정은 업데이트 후 `setup`을 다시 실행해 갱신하세요. Windows에서는 Node 22·24에 포함된 npm의 CMD·PowerShell shim을 사용합니다.
+
 GUI 앱은 터미널과 다른 디렉터리·환경에서 시작될 수 있습니다. 설정을 생성할 때 `--cwd`에 실제 프로젝트의 절대 경로를 지정하세요. 여러 프로젝트를 사용하면 서버 이름과 `--cwd`를 프로젝트별로 구분하세요. 키는 MCP 설정에 복사하지 않고 해당 프로젝트의 `.env`에 둡니다.
 
 ## 클라이언트 설치·업데이트
@@ -102,6 +139,7 @@ Claude Desktop 자동 설치는 macOS와 Windows를 지원합니다. MCP 설정
 
 ```sh
 steercards setup [--client CLIENT] [--local | --npx] [--dry-run] [--cwd PATH] [--env-file PATH] [--url URL] [--mode compact|full]
+  [--setup-code-stdin] [--replace-agent-key]
 ```
 
 `--dry-run`은 파일을 쓰지 않고 예정된 작업만 보여줍니다. 키를 출력하거나 연결 검사를 수행하지 않습니다. `setup`은 코드 클라이언트를 프로젝트 범위에 설치하며 `--global`을 지원하지 않습니다. `--env-file`, `--url`, `--mode`는 생성할 MCP 실행 옵션에도 반영됩니다. 같은 버전에서도 옵션을 바꾸면 해당 설정을 갱신합니다. `--local`과 `--npx`는 함께 사용할 수 없으며 `--npx`는 `setup` 전용 옵션입니다.
@@ -180,11 +218,11 @@ Claude Code, Codex 앱·CLI, Cursor, Claude Desktop 각각의 네이티브 UI
 npm ci
 npm run check
 npm test
-npm run build
+npm run test:package
 npm pack --dry-run
 ```
 
-CI는 Linux·macOS·Windows의 Node 22·24에서 같은 검사를 실행합니다. 테스트는 로컬 fixture를 사용하며 실제 Agent Key가 필요하지 않습니다. 기여 방법은 [CONTRIBUTING.md](CONTRIBUTING.md), 보안 보고는 [SECURITY.md](SECURITY.md)를 참고하세요.
+CI는 Linux·macOS·Windows의 Node 22·24에서 같은 검사를 실행합니다. `test:package`는 빌드한 tarball을 별도 프로젝트에 설치하고 실제 bin·npx 및 생성된 MCP 명령을 실행합니다. Windows에서는 CMD와 PowerShell shim도 검사합니다. 의존성은 lockfile과 `npm ci`의 캐시를 재사용하며 실제 Agent Key가 필요하지 않습니다. 기여 방법은 [CONTRIBUTING.md](CONTRIBUTING.md), 보안 보고는 [SECURITY.md](SECURITY.md)를 참고하세요.
 
 공개 소스는 [velody-ai/steercards-agent-tools](https://github.com/velody-ai/steercards-agent-tools)에서 관리합니다. 안정 버전 GitHub Release를 게시하면 `publish.yml`이 태그·패키지 버전과 main 포함 여부를 확인하고 검사를 다시 실행한 뒤 npm에 게시합니다. 인증은 GitHub OIDC trusted publishing을 사용하며 공개 패키지에 provenance를 연결합니다.
 

package/dist/cli.d.ts

@@ -1,2 +1,2 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --
 export {};

package/dist/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --
 import { parseArgs } from 'node:util';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
@@ -8,9 +8,11 @@ import { Runtime } from './runtime.js';
 import { startServer } from './server.js';
 import { clientConfig, installSkill, exportSkill, packageInfo } from './install.js';
 import { setup } from './setup.js';
+import { setupWithCode } from './setup-with-code.js';
 const help = `Steercards agent tools ${packageInfo.version}
 
 steercards setup [--client CLIENT] [--local | --npx] [--dry-run]
+  [--setup-code-stdin] [--replace-agent-key]
 steercards serve [--mode compact|full]
 steercards tools [query] [--limit 10]
 steercards describe NAME
@@ -28,6 +30,9 @@ setup installs MCP configuration and the skill together; rerun to update both.
 setup uses project scope (Desktop uses its user configuration and a project ZIP).
 --npx explicitly switches an existing local setup to a pinned npm package.
 --dry-run previews setup without writing files. No key is needed for setup.
+--setup-code-stdin reads a one-use installation code, protects the project .env,
+  installs MCP and the skill, then checks the connection. Existing keys are kept.
+--replace-agent-key explicitly replaces the project .env Agent Key.
 config only prints a snippet and never edits host settings.
 --local uses this installation's absolute Node/CLI paths (works before npm release).
 Claude Desktop: upload the skill ZIP, use compact get_guide, or full guide resources.
@@ -64,6 +69,18 @@ async function stdinText() {
     }
     return Buffer.concat(chunks).toString('utf8');
 }
+async function installationCode() {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.length;
+        if (size > 1024)
+            throw new Error('Installation code input is too large.');
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks).toString('utf8').replace(/\r?\n$/, '');
+}
 let secret = process.env.STEERCARDS_AGENT_KEY;
 async function main() {
     const { values, positionals } = parseArgs({ allowPositionals: true, strict: true, options: {
@@ -72,6 +89,7 @@ async function main() {
             client: { type: 'string' }, global: { type: 'boolean' }, output: { type: 'string' },
             limit: { type: 'string' }, connect: { type: 'boolean' }, local: { type: 'boolean' },
             'dry-run': { type: 'boolean' }, npx: { type: 'boolean' },
+            'setup-code-stdin': { type: 'boolean' }, 'replace-agent-key': { type: 'boolean' },
             help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
         } });
     if (values.version) {
@@ -95,6 +113,8 @@ async function main() {
         }
         if (values.global)
             throw new Error('setup uses project scope; omit --global. Claude Desktop configuration is user-scoped.');
+        if (values['replace-agent-key'] && !values['setup-code-stdin'])
+            throw new Error('--replace-agent-key requires --setup-code-stdin.');
         if (values.local && values.npx)
             throw new Error('Choose only one of --local or --npx.');
         let client = values.client;
@@ -114,9 +134,21 @@ async function main() {
             if (!client)
                 throw new Error('No client selected. Nothing was installed.');
         }
-        output(await setup({ ...options, client, local: values.npx ? false : values.local, mode: values.mode, dryRun: values['dry-run'] }));
+        const setupOptions = { ...options, client, local: values.npx ? false : values.local, mode: values.mode, dryRun: values['dry-run'] };
+        if (values['setup-code-stdin']) {
+            const code = await installationCode();
+            secret = code;
+            const result = await setupWithCode({ ...setupOptions, code, replaceAgentKey: values['replace-agent-key'] });
+            output(result);
+            if (!result.ok)
+                process.exitCode = 1;
+        }
+        else
+            output(await setup(setupOptions));
         return;
     }
+    if (values['setup-code-stdin'] || values['replace-agent-key'])
+        throw new Error('Installation code options are only supported by setup.');
     if (values['dry-run'] || values.npx)
         throw new Error('--dry-run and --npx are only supported by setup.');
     if (command === 'config') {

package/dist/install.js

@@ -14,7 +14,9 @@ export function clientConfig(client, options = {}) {
     if (!['compact', 'full'].includes(mode))
         throw new Error('Mode must be compact or full.');
     const cwd = resolve(options.cwd ?? process.cwd());
-    const args = options.local ? [join(packageRoot, 'dist', 'cli.js')] : ['-y', `${packageInfo.name}@${packageInfo.version}`];
+    // Node 22 pre-scans --env-file even after the script path. Protect both the
+    // local Node process and the outer npx process before passing CLI options.
+    const args = options.local ? ['--', join(packageRoot, 'dist', 'cli.js')] : ['-y', '--', `${packageInfo.name}@${packageInfo.version}`];
     args.push('serve', '--cwd', cwd, '--mode', mode);
     if (options.envFile)
         args.push('--env-file', resolve(cwd, options.envFile));

package/dist/setup-credentials.d.ts

@@ -0,0 +1,22 @@
+export interface CredentialOptions {
+    cwd?: string;
+    envFile?: string;
+    savedEnvFile?: string;
+    replaceAgentKey?: boolean;
+    dryRun?: boolean;
+}
+/** Holds only nonsecret metadata in enumerable properties. */
+export interface ProjectCredentials {
+    cwd: string;
+    envFile: string;
+    needsExchange: boolean;
+    actions: string[];
+    verify(): Promise<void>;
+    protect(): Promise<void>;
+    save(token: string): Promise<void>;
+    readKey(): Promise<string>;
+    readMcpUrl(): Promise<string | undefined>;
+    close(): Promise<void>;
+}
+/** Preflight local credentials while holding a project lock shared by every client. */
+export declare function prepareProjectCredentials(options?: CredentialOptions): Promise<ProjectCredentials>;

package/dist/setup-credentials.js

@@ -0,0 +1,326 @@
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { lstat, mkdir, open, readFile, realpath, rename, rm, rmdir } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { parse } from 'dotenv';
+const exec = promisify(execFile);
+const keyName = 'STEERCARDS_AGENT_KEY';
+const keyPattern = /^sc_agent_[A-Za-z0-9_-]{43}$/;
+const missing = (error) => error.code === 'ENOENT';
+async function noSymlink(path) {
+    let current = path;
+    while (true) {
+        try {
+            if ((await lstat(current)).isSymbolicLink())
+                throw new Error('Setup refuses a symbolic link in a credential path.');
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return;
+        current = parent;
+    }
+}
+async function snapshot(path) {
+    await noSymlink(path);
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.nlink !== 1)
+            throw new Error('Credential and ignore files must be ordinary, unlinked files.');
+        if (stat.size > 1024 * 1024)
+            throw new Error('Credential or ignore file is too large to update safely.');
+        const bytes = await readFile(path);
+        try {
+            new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        }
+        catch {
+            throw new Error('Credential and ignore files must use UTF-8.');
+        }
+        return bytes;
+    }
+    catch (error) {
+        if (missing(error))
+            return null;
+        throw error;
+    }
+}
+const same = (left, right) => left === null ? right === null : right !== null && left.equals(right);
+const eol = (text) => text.includes('\r\n') ? '\r\n' : '\n';
+/** Locate assignments without mistaking lines inside another multiline value for keys. */
+function keyValue(text) {
+    const assignments = [];
+    let offset = text.charCodeAt(0) === 0xfeff ? 1 : 0;
+    while (offset < text.length) {
+        const lineEnd = text.indexOf('\n', offset);
+        const end = lineEnd < 0 ? text.length : lineEnd;
+        const line = text.slice(offset, end).replace(/\r$/, '');
+        const match = /^([ \t]*(?:export[ \t]+)?([\w.-]+)[ \t]*(?:=[ \t]*|:[ \t]+))(.*)$/.exec(line);
+        if (!match) {
+            offset = lineEnd < 0 ? text.length : lineEnd + 1;
+            continue;
+        }
+        const start = offset + match[1].length;
+        let valueEnd = start;
+        const quote = text[start];
+        if (["'", '"', '`'].includes(quote)) {
+            valueEnd = start + 1;
+            let closed = false;
+            for (; valueEnd < text.length; valueEnd++) {
+                if (text[valueEnd] !== quote)
+                    continue;
+                let slashes = 0;
+                for (let i = valueEnd - 1; i > start && text[i] === '\\'; i--)
+                    slashes++;
+                if (slashes % 2 === 0) {
+                    valueEnd++;
+                    closed = true;
+                    break;
+                }
+            }
+            if (!closed)
+                throw new Error('Environment file contains an unterminated quoted value. Review it before setup.');
+            const tailEnd = text.indexOf('\n', valueEnd);
+            const tail = text.slice(valueEnd, tailEnd < 0 ? text.length : tailEnd).replace(/\r$/, '');
+            if (!/^[ \t]*(?:#.*)?$/.test(tail))
+                throw new Error('Environment file contains an ambiguous quoted assignment. Review it before setup.');
+            offset = tailEnd < 0 ? text.length : tailEnd + 1;
+        }
+        else {
+            const comment = match[3].indexOf('#');
+            valueEnd = start + (comment < 0 ? match[3] : match[3].slice(0, comment)).trimEnd().length;
+            offset = lineEnd < 0 ? text.length : lineEnd + 1;
+        }
+        if (match[2] === keyName) {
+            if (/[\r\n]/.test(text.slice(start, valueEnd)))
+                throw new Error('A multiline Agent Key assignment cannot be replaced automatically.');
+            const value = parse(`${keyName}=${text.slice(start, valueEnd)}`)[keyName] ?? '';
+            if (/\s/.test(value))
+                throw new Error('The existing Agent Key is invalid. Review its environment assignment before setup.');
+            assignments.push({ start, end: valueEnd, value });
+        }
+    }
+    if (assignments.length > 1)
+        throw new Error('Environment file contains duplicate Agent Key assignments. Resolve them before setup.');
+    return assignments[0];
+}
+function withKey(text, token) {
+    const assignment = keyValue(text);
+    if (assignment)
+        return text.slice(0, assignment.start) + token + text.slice(assignment.end);
+    return text + (text && !text.endsWith('\n') ? eol(text) : '') + `${keyName}=${token}${eol(text)}`;
+}
+function withIgnore(text) {
+    const patterns = text.replace(/^\uFEFF/, '').split(/\r?\n/).map(line => line.trimEnd()).filter(line => line && !line.startsWith('#'));
+    if (patterns.at(-2) === '/.env' && patterns.at(-1) === '/.steercards/')
+        return text;
+    const newline = eol(text);
+    return text + (text && !text.endsWith('\n') ? newline : '') + `# Steercards local credentials${newline}/.env${newline}/.steercards/${newline}`;
+}
+/** Git's index takes precedence over ignore rules; never put a new secret in a tracked file. */
+async function assertUntracked(cwd) {
+    let current = cwd;
+    let repository = false;
+    while (true) {
+        try {
+            await lstat(join(current, '.git'));
+            repository = true;
+            break;
+        }
+        catch (error) {
+            if (!missing(error))
+                throw new Error('Unable to inspect Git tracking before setup.');
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    if (!repository)
+        return;
+    const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith('GIT_')));
+    let output;
+    try {
+        ({ stdout: output } = await exec('git', ['-C', cwd, 'ls-files', '-z', '--', ':(icase,literal).env'], { env, timeout: 10000, maxBuffer: 64 * 1024 }));
+    }
+    catch {
+        throw new Error('Unable to verify Git tracking. Install Git or resolve the repository error before setup.');
+    }
+    if (output)
+        throw new Error('The project .env is tracked by Git. Stop tracking it yourself before installing credentials.');
+}
+async function atomicWrite(path, bytes, mode = 0o600) {
+    await noSymlink(path);
+    const stage = join(dirname(path), `.steercards-${randomUUID()}.tmp`);
+    try {
+        const file = await open(stage, 'wx', mode);
+        try {
+            await file.writeFile(bytes);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(stage, path);
+    }
+    finally {
+        await rm(stage, { force: true });
+    }
+}
+/** Preflight local credentials while holding a project lock shared by every client. */
+export async function prepareProjectCredentials(options = {}) {
+    let cwd;
+    try {
+        cwd = await realpath(resolve(options.cwd ?? process.cwd()));
+        if (!(await lstat(cwd)).isDirectory())
+            throw new Error();
+    }
+    catch {
+        throw new Error('The selected project directory must already exist.');
+    }
+    const envFile = join(cwd, '.env');
+    if (options.envFile !== undefined && resolve(cwd, options.envFile) !== envFile)
+        throw new Error('Automatic credentials only support the project .env. Use --env-file .env.');
+    if (options.envFile === undefined && options.savedEnvFile !== undefined && resolve(cwd, options.savedEnvFile) !== envFile)
+        throw new Error('This installation uses another environment file. Explicitly select --env-file .env to switch before redeeming a code.');
+    const ignoreFile = join(cwd, '.gitignore');
+    const lockPath = join(cwd, '.steercards', 'setup', 'credentials.lock');
+    const created = [];
+    let locked = false;
+    let closed = false;
+    const lockBytes = Buffer.from(`${process.pid}:${randomUUID()}\n`);
+    const ensureDirectory = async (path) => {
+        await noSymlink(path);
+        try {
+            if (!(await lstat(path)).isDirectory())
+                throw new Error('Expected a setup directory.');
+            return;
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        await ensureDirectory(dirname(path));
+        try {
+            await mkdir(path, { mode: 0o700 });
+            created.push(path);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            await noSymlink(path);
+            if (!(await lstat(path)).isDirectory())
+                throw new Error('Expected a setup directory.');
+        }
+    };
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        if (locked && same(lockBytes, await snapshot(lockPath)))
+            await rm(lockPath);
+        for (const path of created.reverse()) {
+            try {
+                await rmdir(path);
+            }
+            catch (error) {
+                if (!missing(error) && !['ENOTEMPTY', 'EEXIST'].includes(error.code ?? ''))
+                    throw error;
+            }
+        }
+    };
+    try {
+        await noSymlink(lockPath);
+        if (!options.dryRun) {
+            await ensureDirectory(dirname(lockPath));
+            try {
+                const file = await open(lockPath, 'wx', 0o600);
+                locked = true;
+                try {
+                    await file.writeFile(lockBytes);
+                }
+                finally {
+                    await file.close();
+                }
+            }
+            catch (error) {
+                if (error.code === 'EEXIST')
+                    throw new Error('Another setup holds the project credential lock. Wait for it to finish.');
+                throw new Error('Unable to acquire the project credential lock. Check directory permissions.');
+            }
+        }
+        let envBefore = await snapshot(envFile);
+        let ignoreBefore = await snapshot(ignoreFile);
+        const existing = keyValue(envBefore?.toString('utf8') ?? '')?.value;
+        const needsExchange = !existing || options.replaceAgentKey === true;
+        const ignoreAfter = Buffer.from(withIgnore(ignoreBefore?.toString('utf8') ?? ''));
+        const ignoreMode = ignoreBefore ? (await lstat(ignoreFile)).mode & 0o777 : 0o644;
+        if (needsExchange && envBefore && ((await lstat(envFile)).mode & 0o200) === 0)
+            throw new Error('The project environment file is read-only. Change its permissions before setup.');
+        if (!same(ignoreBefore, ignoreAfter) && ignoreBefore && (ignoreMode & 0o200) === 0)
+            throw new Error('The project ignore file is read-only. Change its permissions before setup.');
+        await assertUntracked(cwd);
+        const verify = async () => {
+            if (closed)
+                throw new Error('Credential setup is already closed.');
+            await assertUntracked(cwd);
+            if (!same(envBefore, await snapshot(envFile)) || !same(ignoreBefore, await snapshot(ignoreFile)))
+                throw new Error('The project environment or ignore file changed during setup. Review it and retry.');
+        };
+        if (!options.dryRun && (needsExchange || !same(ignoreBefore, ignoreAfter))) {
+            // A real same-directory create/rename probe catches permissions before consuming a code.
+            const probe = join(cwd, `.steercards-probe-${randomUUID()}.tmp`);
+            try {
+                await atomicWrite(probe, Buffer.alloc(0));
+            }
+            catch {
+                throw new Error('The project directory does not allow safe credential writes.');
+            }
+            finally {
+                await rm(probe, { force: true });
+            }
+        }
+        const actions = [...(!same(ignoreBefore, ignoreAfter) ? ['protect project .env and .steercards in .gitignore'] : []), ...(needsExchange ? [existing ? 'replace project Agent Key' : 'save project Agent Key'] : ['keep existing project Agent Key'])];
+        return {
+            cwd, envFile, needsExchange, actions, verify, close,
+            async protect() {
+                if (options.dryRun)
+                    throw new Error('A dry run cannot write files.');
+                await verify();
+                if (!same(ignoreBefore, ignoreAfter)) {
+                    await atomicWrite(ignoreFile, ignoreAfter, ignoreMode);
+                    ignoreBefore = ignoreAfter;
+                }
+            },
+            async save(token) {
+                if (options.dryRun)
+                    throw new Error('A dry run cannot save credentials.');
+                if (!needsExchange)
+                    throw new Error('The existing project Agent Key must be preserved.');
+                if (!keyPattern.test(token))
+                    throw new Error('The exchanged Agent Key has an invalid format.');
+                await verify();
+                if (!same(ignoreBefore, ignoreAfter))
+                    throw new Error('Protect the project environment file before saving credentials.');
+                const bytes = Buffer.from(withKey(envBefore?.toString('utf8') ?? '', token));
+                await atomicWrite(envFile, bytes);
+                envBefore = bytes;
+            },
+            async readKey() {
+                await verify();
+                const value = keyValue(envBefore?.toString('utf8') ?? '')?.value;
+                if (!value)
+                    throw new Error('The project environment file has no Agent Key.');
+                return value;
+            },
+            async readMcpUrl() { await verify(); return parse(envBefore?.toString('utf8') ?? '').STEERCARDS_MCP_URL; },
+        };
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+}

package/dist/setup-with-code.d.ts

@@ -0,0 +1,40 @@
+import { type SetupOptions, type SetupReport, type SetupDependencies } from './setup.js';
+export declare const INSTALL_CODE_PATTERN: RegExp;
+type Receipt = {
+    installationId: string;
+    keyId: string;
+    profileIds: string[];
+};
+export interface CodeSetupReport {
+    ok: boolean;
+    setup: SetupReport | null;
+    credentials: {
+        status: 'not-saved' | 'saved' | 'kept' | 'dry-run';
+        envFile?: string;
+    };
+    doctor: {
+        connected: boolean | null;
+        keySource?: 'env-file';
+        toolCount?: number;
+    };
+    receipt?: Receipt;
+    error?: string;
+    nextSteps: string[];
+}
+export interface CodeSetupOptions extends SetupOptions {
+    code: string;
+    replaceAgentKey?: boolean;
+}
+/** Isolated HTTP, filesystem failure and diagnostic fixtures; never needed by normal callers. */
+export interface CodeSetupDependencies {
+    fetch?: typeof fetch;
+    setup?: SetupDependencies;
+    doctor?: (cwd: string, url: string) => Promise<{
+        connected: boolean;
+        keySource: 'env-file';
+        toolCount?: number;
+    }>;
+}
+/** Redeem only after local setup is ready; keep saved credentials if later configuration fails. */
+export declare function setupWithCode(options: CodeSetupOptions, dependencies?: CodeSetupDependencies): Promise<CodeSetupReport>;
+export {};

package/dist/setup-with-code.js

@@ -0,0 +1,196 @@
+import { DEFAULT_MCP_URL, loadConfig, validateMcpUrl } from './config.js';
+import { Runtime } from './runtime.js';
+import { setup } from './setup.js';
+import { prepareProjectCredentials } from './setup-credentials.js';
+import { realpath, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+export const INSTALL_CODE_PATTERN = /^sc_install_[A-Za-z0-9_-]{43}$/;
+const tokenPattern = /^sc_agent_[A-Za-z0-9_-]{43}$/;
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const errors = {
+    AGENT_INSTALL_CODE_NOT_FOUND: 'Installation code was not found. Create a new code in Steercards.',
+    AGENT_INSTALL_CODE_EXPIRED: 'Installation code expired. Create a new code in Steercards.',
+    AGENT_INSTALL_CODE_REVOKED: 'Installation code was revoked. Create a new code in Steercards.',
+    AGENT_INSTALL_CODE_CONSUMED: 'Installation code was already used. Check the issued Agent Key in Steercards before creating a new code.',
+    AGENT_INSTALL_CODE_PROFILE_INVALID: 'The selected profiles are no longer available. Create a new installation code.',
+    AGENT_INSTALL_CODE_OWNER_INVALID: 'The installation owner is no longer available. Sign in to Steercards and create a new code.',
+    RATE_LIMITED: 'Too many installation attempts. Wait before creating another request.',
+};
+const recovery = 'The code may have been consumed. Create a new code and remove any unused issued Agent Key in Steercards. Never paste the Agent Key into chat.';
+async function boundedJson(response) {
+    if (!response.headers.get('content-type')?.toLowerCase().includes('application/json')) {
+        await response.body?.cancel();
+        throw new Error('Installation service returned an invalid response.');
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('Installation service returned an empty response.');
+    let size = 0;
+    const chunks = [];
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 64 * 1024) {
+                await reader.cancel();
+                throw new Error('Installation service response is too large.');
+            }
+            chunks.push(value);
+        }
+        try {
+            return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        catch {
+            throw new Error('Installation service returned invalid JSON.');
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+async function exchange(code, url, fetcher) {
+    let response;
+    try {
+        response = await fetcher(new URL('/api/agent-setup/exchange', url), {
+            method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+            body: JSON.stringify({ code }), redirect: 'error', signal: AbortSignal.timeout(15000),
+        });
+    }
+    catch {
+        throw new Error(`Unable to confirm installation code exchange. ${recovery}`);
+    }
+    let value;
+    try {
+        value = await boundedJson(response);
+    }
+    catch {
+        throw new Error(`Installation service returned an invalid or incomplete response. ${recovery}`);
+    }
+    if (!response.ok) {
+        const errorCode = value?.error?.code;
+        const message = typeof errorCode === 'string' && Object.hasOwn(errors, errorCode) ? errors[errorCode] : undefined;
+        throw new Error(message ?? `Installation service rejected the request (HTTP ${response.status}). ${recovery}`);
+    }
+    if (!value || typeof value.token !== 'string' || !tokenPattern.test(value.token)
+        || typeof value.installationId !== 'string' || !uuidPattern.test(value.installationId)
+        || !value.key || typeof value.key.id !== 'string' || !uuidPattern.test(value.key.id) || !Array.isArray(value.profileIds)
+        || value.profileIds.length > 30 || value.profileIds.some((id) => typeof id !== 'string' || !uuidPattern.test(id))
+        || new Set(value.profileIds).size !== value.profileIds.length)
+        throw new Error(`Installation service returned invalid credentials. ${recovery}`);
+    return { token: value.token, receipt: { installationId: value.installationId, keyId: value.key.id, profileIds: value.profileIds } };
+}
+async function doctor(cwd, url) {
+    // Explicitly inspect the stored file, regardless of the invoking agent's environment.
+    const config = await loadConfig({ cwd, envFile: '.env', url, env: {} });
+    const runtime = new Runtime(config);
+    const timeout = setTimeout(() => { void runtime.close().catch(() => { }); }, 15000);
+    timeout.unref();
+    try {
+        const tools = await runtime.listTools();
+        const result = await runtime.callTool('list_workspaces', {});
+        let failed = result.isError === true || result.structuredContent?.ok === false;
+        for (const item of result.content)
+            if (item.type === 'text') {
+                try {
+                    if (JSON.parse(item.text)?.ok === false)
+                        failed = true;
+                }
+                catch { /* Ordinary text is allowed. */ }
+            }
+        return { connected: !failed, keySource: 'env-file', toolCount: tools.length };
+    }
+    finally {
+        clearTimeout(timeout);
+        await runtime.close();
+    }
+}
+/** Redeem only after local setup is ready; keep saved credentials if later configuration fails. */
+export async function setupWithCode(options, dependencies = {}) {
+    const report = { ok: false, setup: null, credentials: { status: 'not-saved' }, doctor: { connected: null }, nextSteps: [] };
+    let credentials;
+    let token;
+    let attemptedExchange = false;
+    let mcpUrl;
+    try {
+        if (!INSTALL_CODE_PATTERN.test(options.code))
+            throw new Error('Installation code has an invalid format. Copy a fresh setup prompt from Steercards.');
+        try {
+            if (!(await stat(await realpath(resolve(options.cwd ?? process.cwd())))).isDirectory())
+                throw new Error();
+        }
+        catch {
+            throw new Error('The selected project directory must already exist.');
+        }
+        mcpUrl = validateMcpUrl(options.url ?? DEFAULT_MCP_URL);
+        report.setup = await setup({ ...options, url: mcpUrl }, {
+            ...dependencies.setup,
+            async afterPreflight(context) {
+                credentials = await prepareProjectCredentials({ cwd: context.cwd, envFile: options.envFile, savedEnvFile: context.envFile, replaceAgentKey: options.replaceAgentKey, dryRun: context.dryRun });
+                report.credentials.envFile = credentials.envFile;
+                const savedUrl = await credentials.readMcpUrl();
+                if (savedUrl && new URL(validateMcpUrl(savedUrl)).origin !== new URL(mcpUrl).origin && options.url === undefined)
+                    throw new Error('The project uses another MCP server. Explicitly select its --url before redeeming an installation code.');
+                if (context.dryRun) {
+                    report.credentials.status = 'dry-run';
+                    return;
+                }
+                await credentials.protect();
+                if (!credentials.needsExchange) {
+                    report.credentials.status = 'kept';
+                    return;
+                }
+                await credentials.verify();
+                attemptedExchange = true;
+                const claimed = await exchange(options.code, mcpUrl, dependencies.fetch ?? fetch);
+                token = claimed.token;
+                report.receipt = claimed.receipt;
+                try {
+                    await credentials.save(token);
+                }
+                catch {
+                    throw new Error(`The issued Agent Key could not be saved safely. ${recovery}`);
+                }
+                report.credentials.status = 'saved';
+            },
+        });
+        report.setup.actions.unshift(...credentials.actions);
+        report.setup.nextSteps = report.setup.nextSteps.filter(step => !step.startsWith('Set STEERCARDS_AGENT_KEY'));
+        if (options.dryRun) {
+            report.ok = true;
+            report.nextSteps = ['Run setup again without --dry-run to complete installation.'];
+            return report;
+        }
+        try {
+            report.doctor = await (dependencies.doctor ?? doctor)(credentials.cwd, mcpUrl);
+        }
+        catch {
+            report.doctor = { connected: false, keySource: 'env-file' };
+        }
+        report.ok = report.doctor.connected === true;
+        report.nextSteps = [...report.setup.nextSteps, ...(!report.ok ? ['Credentials and setup were preserved. Run doctor --connect after checking the MCP server. Do not redeem the code again.'] : [])];
+        if (!report.ok)
+            report.error = 'Setup completed, but the connection check did not succeed.';
+    }
+    catch (error) {
+        let message = error instanceof Error ? error.message : 'Installation failed.';
+        for (const secret of [options.code, token])
+            if (secret)
+                message = message.split(secret).join('[REDACTED]');
+        report.error = message;
+        report.nextSteps = report.credentials.status === 'saved' || report.credentials.status === 'kept'
+            ? ['The project .env was preserved. Fix the configuration conflict and rerun setup without an installation code, then doctor --connect.']
+            : [attemptedExchange ? recovery : 'Resolve the local setup issue and rerun the prompt before the code expires.'];
+    }
+    finally {
+        try {
+            await credentials?.close();
+        }
+        catch {
+            report.ok = false;
+            report.error = 'Setup could not release its local lock. Review the project setup lock before retrying.';
+        }
+    }
+    return report;
+}

package/dist/setup.d.ts

@@ -29,6 +29,12 @@ export interface SetupDependencies {
     version?: string;
     beforeCommit?: () => Promise<void>;
     beforeWrite?: (path: string, index: number) => Promise<void>;
+    /** Runs under the config lock after all destinations are checked; dry runs never redeem codes. */
+    afterPreflight?: (context: {
+        cwd: string;
+        envFile?: string;
+        dryRun: boolean;
+    }) => Promise<void>;
 }
 /** Configure MCP and the matching skill together, preserving unrelated client data. */
 export declare function setup(options: SetupOptions, dependencies?: SetupDependencies): Promise<SetupReport>;

package/dist/setup.js

@@ -349,7 +349,11 @@ export async function setup(options, dependencies = {}) {
         ? [`Restart Claude Desktop to load the MCP server.`, `Upload ${zipPath} in Claude's skill settings. Repeat the upload after a skill update.`, 'Set STEERCARDS_AGENT_KEY in the project .env or the referenced env file before using MCP.']
         : ['Restart or reload your client to load the MCP server and skill.', 'Set STEERCARDS_AGENT_KEY in the project .env or the referenced env file before using MCP.'];
     const report = { client, version, status: options.dryRun ? 'dry-run' : plan.size ? previous ? 'updated' : 'installed' : 'unchanged', paths, actions, nextSteps };
-    if (options.dryRun || !plan.size)
+    if (options.dryRun) {
+        await dependencies.afterPreflight?.({ cwd, envFile: effective.envFile, dryRun: true });
+        return report;
+    }
+    if (!plan.size && !dependencies.afterPreflight)
         return report;
     // This is an ordinary-failure transaction, not a crash-atomic multi-file commit.
     const createdDirectories = [];
@@ -398,6 +402,29 @@ export async function setup(options, dependencies = {}) {
         }
         if (skillPath)
             await checkSkillTree(skillPath);
+        if (dependencies.afterPreflight) {
+            // Exercise destination directories before a one-use credential is consumed.
+            for (const parent of new Set([...plan.keys()].map(path => dirname(path)))) {
+                await ensureDirectory(parent);
+                const probe = join(parent, `.steercards-write-probe-${randomUUID()}.tmp`);
+                try {
+                    await atomicWrite(probe, Buffer.alloc(0), 0o600, ensureDirectory);
+                }
+                catch {
+                    throw new Error('A setup destination does not allow safe writes. Check its directory permissions.');
+                }
+                finally {
+                    await rm(probe, { force: true });
+                }
+            }
+            for (const [path, before] of baselines) {
+                if (!sameSnapshot(before, await snapshot(path)))
+                    throw new Error('A setup destination changed during preflight. No credential was requested.');
+                if (plan.has(path) && before && (before.mode & 0o200) === 0)
+                    throw new Error('A setup destination is read-only. Change its permissions before installing credentials.');
+            }
+            await dependencies.afterPreflight({ cwd, envFile: effective.envFile, dryRun: false });
+        }
         let index = 0;
         for (const [path, bytes] of plan) {
             await dependencies.beforeWrite?.(path, index++);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steercards/agent-tools",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Progressive MCP discovery, CLI and agent skills for Steercards",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,7 @@
   "scripts": {
     "build": "tsc",
     "test": "node --import tsx --test test/*.test.ts",
+    "test:package": "npm run build && node --test test/package.test.mjs",
     "check": "tsc --noEmit",
     "prepack": "npm run build"
   },

package/skills/steercards/SKILL.md

@@ -7,6 +7,12 @@ description: Manage Steercards workspaces, boards, cards, files and agent collab
 
 Use the connected Steercards toolkit MCP or its `steercards` CLI. Authentication comes from `STEERCARDS_AGENT_KEY`, including a local dotenv file configured for the toolkit. Keep credentials out of tool arguments, logs and committed files. GUI hosts can use an absolute env-file path; their working directory may differ from the project.
 
+## Connecting from an installation prompt
+
+When the user provides a Steercards installation prompt, run its `setup --setup-code-stdin` command in the intended project with `--cwd . --env-file .env` and the prompt's explicit MCP `--url`. Pass the short-lived code through stdin. The installer exchanges it once, saves the Agent Key only in the project `.env`, protects Git ignore rules, installs MCP and this skill, and checks the connection. Report the safe installation summary; never print the resulting key or inspect the exchange body for chat output.
+
+An existing project key is kept without consuming the code. Replace it only when requested, using `--replace-agent-key`. Automatic credential writes support only the project root `.env`. Local configuration/skill conflicts or a tracked `.env` must be resolved before redeeming. If credentials were saved but installation or doctor failed, preserve `.env` and rerun normal setup/doctor without a code. After an uncertain exchange or failed key save, ask for a fresh app-generated prompt and direct the user to remove unused issued keys in Steercards; do not replay the code or request the long-lived key in chat. Client restart/reconnect and Desktop Skill ZIP upload may still be needed.
+
 ## Discover only what the task needs
 
 1. Search capabilities: `steercards_search_tools({query: "card context", limit: 5})`.

package/skills/steercards/references/collaboration.md

@@ -14,6 +14,12 @@ Only one of `before`, `after`, `pageCursor`, `refreshKeys` is allowed per call.
 
 `request_human_check` names a real workspace member, prod/local environment and action/expected-result steps. It creates an item in the person's check inbox. Optional pass/fail business-status transitions must reflect the intended task. Query `list_human_checks` / `get_human_check` for actual verdicts and evidence. Creating the request is not a passed check, and "human check" is not a board status to invent.
 
+Describe the live tool before constructing a request. Verification can optionally provide `resultOptions: [{id,label,description?,verdict}]`: 2–6 ordered choices shared by every step. IDs are unique ASCII letters/digits/underscore/hyphen (1–64 characters), labels are 1–120 characters and descriptions at most 500. Each verdict explicitly means `pass`, `fail` or `inconclusive`; never infer meaning from the label. Omit resultOptions to retain legacy pass/fail choices. Explicit null and mixing resultOptions with a question are invalid.
+
+For example, use `works / Normal operation / pass`, `partial / Partly working / fail`, and `unable / Cannot verify / inconclusive`. Any failed step makes the result `failed`; otherwise any inconclusive step makes it `answered`; only all-pass becomes `passed`. A fail requires a memo. Inconclusive permits an optional memo and never means success. Verification `followUps` uses `onPassed`, `onFailed` and `onAnswered` once after aggregation. Omitted follow-ups keep the card state; inconclusive never falls back to legacy onFailStatus. For per-choice moves, use a single-selection question instead.
+
+The assigned person chooses in the web inbox, saves each step, then explicitly submits the final response. Selection and step saving do not finalize the check or create the completion comment/webhook. Do not answer on the person's behalf. Read `steps[].selectedOptionId` and `selectedOptionSnapshot` for original ID, label, description and verdict; final `response` preserves resultOptions and steps. Processed history, comments and `human_check.completed` retain the original choice. Inspect actual `followUpResult` as current card state, permissions or workflow may block a requested move.
+
 `set_agent_status` / `clear_agent_status` expose working/input-wait/error. A waiting question can create a pinned agent comment; it is not equivalent to a step-by-step human check. Working status needs refresh at least every ten minutes. Check claim fences when the card is claim-managed.
 
 ## Reserve shared resources