@tienne/gestalt 0.72.1 → 0.72.2

package/CLAUDE.md

@@ -115,6 +115,28 @@ plugin/.mcp.json                  Grok MCP (plugin/mcp.json과 동일)
 - `plugin/skills/review/SKILL.md`가 `../../role-agents/`를 참조한다. 스킬과 에이전트를 함께 옮겨야 이 상대 깊이가 유지된다.
 - 자산 디렉토리 기본값은 `src/core/config.ts`에 `skillsDir`, `agentsDir`, `roleAgentsDir`, `reviewAgentsDir`, `personasDir` 다섯 개로 있다. 경로를 바꾸면 전부 함께 고친다.
 
+### MCP 기동 경로
+
+클라이언트마다 서버를 띄우는 방식이 다르다.
+
+```
+.mcp.json                 Claude — sh로 scripts/mcp-serve.sh를 찾아 실행
+.claude-plugin/.mcp.json  .mcp.json과 내용 동일 (해석 기준 디렉토리가 모호해 양쪽에 둔다)
+plugin/mcp.json           Codex — npx, 버전 핀
+plugin/.mcp.json          Grok(배포) — plugin/mcp.json과 동일
+.grok/config.toml         Grok(이 레포 개발용) — scripts/grok-mcp-serve.sh
+```
+
+- `npx`는 버전을 박아도 기동할 때마다 레지스트리를 조회한다. 캐시가 비면 20초, 레지스트리에 못 닿으면 70초를 매달린다. Claude Code의 기동 제한은 30초라 둘 다 `Connection closed`로 끊긴다.
+- `startup_timeout_sec`와 `tool_timeout_sec`는 Codex 키다. Claude Code는 안 읽고 `MCP_TIMEOUT` 환경변수만 본다. Claude 매니페스트에 넣어봐야 무시된다.
+- `scripts/mcp-serve.sh`가 그 셋을 처리한다. nvm, fnm, Volta, Homebrew에서 Node >= 20을 찾는다 (GUI 세션은 PATH에 버전 매니저가 없다). 전역 `gestalt`가 있으면 그걸 쓰고 없으면 `npx --offline`으로 캐시에서 해석한다.
+- 그 스크립트는 npx로 서버를 띄우지 않고 bin 경로만 받아와 직접 exec한다. npx가 cwd의 로컬 패키지를 먼저 보기 때문에, node_modules 없는 gestalt 체크아웃 안에서는 `gestalt: command not found`로 죽는다. 그래서 해석은 `cd /`에서 한다.
+- 전역 `gestalt`가 깔려 있으면 핀보다 그게 이긴다. 누가 `npm i -g`를 했다는 건 이 체크아웃이 번들한 것보다 구체적인 선택이라서다. 대신 어느 쪽을 썼는지 stderr에 적어 버전이 어긋났을 때 로그에서 보이게 한다.
+- 매니페스트의 `sh -c`는 `${CLAUDE_PLUGIN_ROOT}`를 먼저 본다. 거기서 스크립트를 찾으면 `GESTALT_LAUNCHER`는 아예 안 본다. 플러그인으로 설치된 상태에서는 그 변수가 안 걸린다는 뜻이다. 플러그인 없이 이 레포만 연 경우에만 차례가 온다. 그때도 **절대 경로만** 받는다 — 상대 경로를 허용하면 남의 레포를 열었을 때 거기 있는 동명 실행 파일이 서버 대신 도는 자리가 된다.
+- 그 `sh -c`의 최후 폴백도 버전이 핀되어 있다. 거기까지 왔으면 스크립트를 못 찾은 것이다. 스크립트가 없으면 `package.json`도 없어 런타임에 버전을 못 읽는다. 그래서 그 자리만은 `sync-version.ts`가 문자열에 직접 박는다.
+- 네 매니페스트의 버전 핀을 `scripts/sync-version.ts`가 릴리즈마다 함께 갱신한다. `plugin/*`는 인자 하나가 통째로 스펙이고 Claude 쪽은 `sh` 문자열 안에 박혀 있는데, 같은 정규식으로 둘 다 친다.
+- `command: "sh"`라서 Windows 호스트에서는 안 뜬다. 그쪽은 전역 설치 후 `command: "gestalt"`로 안내한다.
+
 ## Conventions
 - MCP 서버에서 `console.log` 금지 → `log()` stderr 유틸 사용
 - `noUncheckedIndexedAccess` 환경 → 배열 인덱스·regex 캡처그룹에 `!` 단언 필수

package/README.ko.md

@@ -161,14 +161,18 @@ claude plugin install gestalt@gestalt
 
 ### 옵션 2: Claude Code Desktop
 
-Claude Code Desktop 설정에서 `settings.json` (또는 `claude_desktop_config.json`)에 추가하세요:
+먼저 전역 설치한 다음, 설정이 그 바이너리를 가리키게 하세요:
+
+```bash
+npm install -g @tienne/gestalt
+```
 
 ```json
 {
   "mcpServers": {
     "gestalt": {
-      "command": "npx",
-      "args": ["-y", "@tienne/gestalt"]
+      "command": "gestalt",
+      "args": ["serve"]
     }
   }
 }
@@ -176,13 +180,15 @@ Claude Code Desktop 설정에서 `settings.json` (또는 `claude_desktop_config.
 
 Claude Code Desktop을 재시작하면 MCP 도구가 즉시 사용 가능해요. 슬래시 커맨드는 플러그인 설치 또는 별도 스킬 설정이 필요해요.
 
+`npx -y @tienne/gestalt`도 되긴 하는데, 그 전에 [기동 타임아웃](#기동-타임아웃)을 읽어보세요. 데스크톱 앱이 이 문제에 제일 잘 걸립니다.
+
 ---
 
 ### 옵션 3: Claude Code CLI
 
 ```bash
-# claude CLI로 추가
-claude mcp add gestalt -- npx -y @tienne/gestalt
+npm install -g @tienne/gestalt
+claude mcp add gestalt -- gestalt serve
 ```
 
 또는 `~/.claude/settings.json`을 직접 편집하세요:
@@ -191,8 +197,8 @@ claude mcp add gestalt -- npx -y @tienne/gestalt
 {
   "mcpServers": {
     "gestalt": {
-      "command": "npx",
-      "args": ["-y", "@tienne/gestalt"]
+      "command": "gestalt",
+      "args": ["serve"]
     }
   }
 }
@@ -200,6 +206,26 @@ claude mcp add gestalt -- npx -y @tienne/gestalt
 
 ---
 
+### 기동 타임아웃
+
+서버가 붙을 때는 붙고 어떨 때는 `Connection closed`로 끊긴다면, 원인은 대개 Gestalt가 아니라 `npx`입니다. 알아둘 게 셋입니다.
+
+**npx는 기동할 때마다 레지스트리를 조회합니다.** 버전을 정확히 박아도 마찬가지예요. npm 상대로 재봤더니 캐시가 데워졌을 때 1.9초, 비었을 때 20초, 레지스트리에 못 닿으면 70초를 매달린 뒤 실패했습니다. Claude Code는 stdio 서버에 `initialize` 응답까지 30초를 주므로 콜드 상태와 오프라인 상태가 둘 다 끊긴 연결로 나타납니다. 전역 설치해서 `gestalt serve`를 직접 부르면 이 과정이 통째로 사라집니다.
+
+**GUI로 띄운 세션은 PATH가 다릅니다.** 터미널 밖에서 시작한 것들 — 데스크톱 앱, 런처, launchd — 은 버전 매니저가 빠진 PATH를 물려받아서 `npx`를 아예 못 찾고 즉시 죽습니다. `command`에 절대 경로를 주거나 서버 항목에 `env.PATH`를 지정하세요.
+
+**Claude Code에서 `startup_timeout_sec`는 아무 일도 안 합니다.** 그건 Codex 키예요. Claude Code는 `MCP_TIMEOUT` 환경변수(밀리초)를 읽으므로 `settings.json`에 넣어야 Claude Code 프로세스까지 전달됩니다:
+
+```json
+{
+  "env": { "MCP_TIMEOUT": "180000" }
+}
+```
+
+플러그인 설치(옵션 1)는 앞의 둘을 `scripts/mcp-serve.sh`가 알아서 처리해요. Node는 nvm, fnm, Volta, Homebrew 밑에서 찾고요. 전역 설치된 `gestalt`가 있으면 그걸 씁니다. 없으면 핀된 버전을 npm 캐시에서 바로 해석하고요.
+
+---
+
 ### 옵션 4: OpenAI Codex 플러그인
 
 Claude Code 플러그인과 똑같이 MCP 서버랑 워크플로 스킬 19개를 한 번에 받아요.

package/README.md

@@ -132,14 +132,18 @@ What you get:
 
 ### Option 2: Claude Code Desktop
 
-Add this to your `settings.json` (or `claude_desktop_config.json`) and restart:
+Install once, then point the config at the installed binary:
+
+```bash
+npm install -g @tienne/gestalt
+```
 
 ```json
 {
   "mcpServers": {
     "gestalt": {
-      "command": "npx",
-      "args": ["-y", "@tienne/gestalt"]
+      "command": "gestalt",
+      "args": ["serve"]
     }
   }
 }
@@ -147,12 +151,15 @@ Add this to your `settings.json` (or `claude_desktop_config.json`) and restart:
 
 MCP tools are available immediately after restart. Slash commands require the plugin or manual skills setup.
 
+`npx -y @tienne/gestalt` works too, but read [Startup timeouts](#startup-timeouts) first — the desktop app is the setup most likely to hit them.
+
 ---
 
 ### Option 3: Claude Code CLI
 
 ```bash
-claude mcp add gestalt -- npx -y @tienne/gestalt
+npm install -g @tienne/gestalt
+claude mcp add gestalt -- gestalt serve
 ```
 
 Or add directly to `~/.claude/settings.json`:
@@ -161,8 +168,8 @@ Or add directly to `~/.claude/settings.json`:
 {
   "mcpServers": {
     "gestalt": {
-      "command": "npx",
-      "args": ["-y", "@tienne/gestalt"]
+      "command": "gestalt",
+      "args": ["serve"]
     }
   }
 }
@@ -170,6 +177,26 @@ Or add directly to `~/.claude/settings.json`:
 
 ---
 
+### Startup timeouts
+
+If the server connects sometimes and reports `Connection closed` other times, the cause is almost always `npx`, not Gestalt. Three things are worth knowing.
+
+**npx reaches the registry on every start.** Pinning an exact version does not change that. Measured against npm: 1.9s on a warm cache, 20s on a cold one, and a 70s hang before failing when the registry is unreachable. Claude Code gives a stdio server 30s to answer `initialize`, so the cold and offline cases both surface as a closed connection. Installing the package globally and calling `gestalt serve` skips all of it.
+
+**GUI-launched sessions have a different PATH.** Anything started outside a terminal — the desktop app, a launcher, launchd — inherits a PATH with no version manager on it, so `npx` is not found and the server dies instantly. Give `command` an absolute path, or set `env.PATH` on the server entry.
+
+**`startup_timeout_sec` does nothing in Claude Code.** That key belongs to Codex. Claude Code reads the `MCP_TIMEOUT` environment variable (milliseconds) instead, so it goes in `settings.json`, where it lands in the Claude Code process:
+
+```json
+{
+  "env": { "MCP_TIMEOUT": "180000" }
+}
+```
+
+The plugin install (Option 1) already handles the first two through `scripts/mcp-serve.sh`: it finds Node under nvm, fnm, Volta, or Homebrew, prefers a globally installed `gestalt`, and otherwise resolves the pinned version from the npm cache, falling back to the network only when the cache misses.
+
+---
+
 ### Option 4: OpenAI Codex Plugin
 
 Bundles the MCP server and all 19 workflow skills, the same way the Claude Code plugin does.

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tienne/gestalt",
-  "version": "0.72.1",
+  "version": "0.72.2",
   "description": "TypeScript AI Development Harness - Gestalt psychology-driven requirement clarification",
   "type": "module",
   "main": "./dist/src/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tienne/gestalt",
-  "version": "0.72.1",
+  "version": "0.72.2",
   "description": "TypeScript AI Development Harness - Gestalt psychology-driven requirement clarification",
   "type": "module",
   "main": "./dist/src/index.js",

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gestalt",
-  "version": "0.72.1",
+  "version": "0.72.2",
   "description": "Gestalt psychology-driven AI development harness. Transforms scattered requirements into structured, validated specifications through interactive interviews.",
   "author": {
     "name": "tienne"

package/plugin/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "gestalt": {
       "command": "npx",
-      "args": ["-y", "@tienne/gestalt", "serve"],
+      "args": ["-y", "@tienne/gestalt@0.72.2", "serve"],
       "startup_timeout_sec": 180,
       "tool_timeout_sec": 900
     }

package/plugin/mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "gestalt": {
       "command": "npx",
-      "args": ["-y", "@tienne/gestalt", "serve"],
+      "args": ["-y", "@tienne/gestalt@0.72.2", "serve"],
       "startup_timeout_sec": 180,
       "tool_timeout_sec": 900
     }