@design-ai/cli 4.55.0 → 4.56.0

package/docs/external-status.md

@@ -1,32 +1,47 @@
 # External Publication Status
 
-> Checked: 2026-06-23
-> Scope: npm registry, GitHub Pages, VS Code Marketplace
+> Checked: 2026-07-02
+> Scope: npm registry, GitHub Pages, Homebrew tap, VS Code Marketplace, Claude/Codex MCP
 
 ## Summary
 
-Local release readiness is verified and GitHub Pages docs are publicly reachable. The npm package name in `package.json` and the VS Code Marketplace extension id still returned no public listing at the time of this check.
+Local release readiness is verified, GitHub Pages docs are publicly reachable, GitHub Release `v4.56.0` is published, and the Homebrew tap formula points at the `v4.56.0` release source tarball with a verified SHA-256. npm is still publicly published at `@design-ai/cli@4.55.0`; the latest `v4.56.0` npm publish attempt authenticated as `sungjin9288`, passed package smoke, signed provenance, then failed on registry `E403` because npm requires either two-factor authentication during publish or a granular access token with Bypass 2FA enabled. Replace `NPM_TOKEN` with a publish-capable granular token for `@design-ai/cli` that has Bypass 2FA enabled, or migrate the workflow to npm Trusted Publishing, before rerunning. The VS Code extension `sungjin.design-ai-vscode` is published to the VS Code Marketplace at version `0.4.1`; the Gallery API is reachable. The public npm MCP entrypoint and the local Claude Code / Codex MCP client registrations were rechecked on 2026-07-02.
 
 ## Results
 
 | Surface | Checked target | Result | Evidence |
 |---|---|---|---|
-| npm registry | `@design-ai/cli` | Not published or not publicly accessible: npm returned `E404` | `evidence/cli-logs/npm-registry-status.log` |
+| npm registry | `@design-ai/cli` | Published latest remains `4.55.0`; public registry smoke passed for `@design-ai/cli@4.55.0`. Latest `v4.56.0` publish run `28568106904` authenticated `NPM_TOKEN`, passed package smoke, signed provenance, then failed with `E403` because npm requires 2FA during publish or a granular access token with Bypass 2FA enabled. | `evidence/cli-logs/npm-registry-status.log`, `evidence/cli-logs/npm-registry-smoke.log`, `evidence/cli-logs/npm-publish-v4.56.0-failed.log`, `evidence/cli-logs/npm-publish-v4.56.0-preflight-failed.log`, `evidence/cli-logs/npm-publish-v4.56.0-bypass-2fa-required-20260702.log` |
 | GitHub Pages | `https://sungjin9288.github.io/design-ai/` | Published and reachable: HTTP `200`, design-ai MkDocs page rendered | `evidence/cli-logs/github-pages-status.log` |
-| VS Code Marketplace | `sungjin.design-ai-vscode` | No public Marketplace listing found for the publisher/extension id | `evidence/cli-logs/vscode-marketplace-status.log` |
+| Homebrew tap | `Formula/design-ai.rb` | Formula pinned to `v4.56.0` release source tarball with SHA-256 `507d2519296497defcd486c0ffc2b5164967a0bc540ddc31bc89502350688212`; Ruby syntax and `brew style` passed | `evidence/cli-logs/homebrew-formula-status.log` |
+| VS Code Marketplace | `sungjin.design-ai-vscode` | Published: run `28431571256` published `v0.4.1`, and the Marketplace Gallery API returned visible version `0.4.1` on 2026-07-02. | `evidence/cli-logs/vscode-marketplace-status.log`, `evidence/cli-logs/vscode-marketplace-secret-status.log`, `evidence/cli-logs/vscode-extension-vsce-package.log`, `evidence/cli-logs/vscode-publish-workflow-status.log` |
+| GitHub Release | `v4.56.0` | Published with release tarball asset `design-ai-cli-4.56.0.tgz` | `evidence/cli-logs/github-release-v4.56.0.log` |
+| MCP server | `@design-ai/cli@4.55.0` / local clone | Public npm `design-ai-mcp` responds to initialize and tools/list with 10 tools; local Codex and Claude Code both report `design-ai` MCP as configured and connected. | `evidence/cli-logs/design-ai-mcp-public-registry-smoke.log`, `evidence/cli-logs/design-ai-mcp-client-status.log` |
 
 ## Interpretation
 
 - The repository is locally release-ready based on `npm run release:check`.
 - GitHub Pages docs can now be described as publicly deployed.
-- Public npm install and Marketplace install claims should not be used in portfolio or README copy until those surfaces are published and rechecked.
-- For portfolio wording, describe npm/package/Marketplace as "prepared for" or "local/package smoke verified", not "publicly shipped".
+- Public npm install can be described as published and smoke-tested at `4.55.0`; `4.56.0` must not be described as npm-published until `NPM_TOKEN` is replaced with a Bypass 2FA-enabled granular token, or the workflow is migrated to npm Trusted Publishing, and the publish workflow succeeds.
+- Homebrew tap install can now be described as pinned to the `v4.56.0` release tarball; full tap audit/install/test remains a maintainer-side verification step because this Homebrew version rejects path-based `brew audit Formula/...` calls.
+- VS Code Marketplace can now be described as published and publicly reachable at version `0.4.1`.
+- Claude Code and Codex can now be described as locally connected to the clone-backed `design-ai` MCP server, while public npm users can verify the published `design-ai-mcp` entrypoint from a clean working directory.
 
 ## Recheck Commands
 
 ```bash
 npm view @design-ai/cli version name time.modified dist-tags --json
 curl -sS -L -o /tmp/design-ai-pages.html -w 'http_code=%{http_code}\nurl_effective=%{url_effective}\n' https://sungjin9288.github.io/design-ai/
+curl -sL https://github.com/sungjin9288/design-ai/archive/refs/tags/v4.56.0.tar.gz | shasum -a 256
+ruby -c Formula/design-ai.rb
+brew style Formula/design-ai.rb
+gh release view v4.56.0 --repo sungjin9288/design-ai --json tagName,isDraft,isPrerelease,publishedAt,name,url,assets
+gh run view 28561753737 --repo sungjin9288/design-ai --log-failed
+gh run view 28562868536 --repo sungjin9288/design-ai --log-failed
+gh run view 28568106904 --repo sungjin9288/design-ai --log-failed
+npm exec --yes --package=@design-ai/cli@4.55.0 -- design-ai-mcp
+codex mcp get design-ai
+claude mcp list
 curl -sS -H 'Content-Type: application/json' \
   -H 'Accept: application/json;api-version=7.2-preview.1' \
   -X POST https://marketplace.visualstudio.com/_apis/public/gallery/extensionquery \

package/docs/integrations/design-ai-mcp-server.md

@@ -35,6 +35,19 @@ design-ai mcp
 design-ai-mcp
 ```
 
+To verify the public npm package without installing it globally, run the one-shot command from a clean directory outside a `@design-ai/cli` source checkout:
+
+```bash
+tmp="$(mktemp -d)"
+cd "$tmp"
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25"}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+  | npm exec --yes --package=@design-ai/cli@4.55.0 -- design-ai-mcp
+```
+
+Running that one-shot command from the package source root can make npm prefer the local checkout context, which may hide the temporary package bin shim.
+
 Do not run the server as a normal terminal command unless an MCP client is connected. It waits for newline-delimited JSON-RPC messages on stdin and writes MCP responses to stdout.
 
 ## Connect Claude Code
@@ -145,6 +158,12 @@ Run the unit and subprocess smoke tests:
 node --test cli/lib/mcp-server.test.mjs
 ```
 
+Run the package smoke self-test when changing the packaged MCP entrypoint:
+
+```bash
+npm run package:smoke:self-test
+```
+
 Run a protocol smoke manually:
 
 ```bash
@@ -156,6 +175,19 @@ printf '%s\n' \
 
 The output must contain valid one-line JSON-RPC responses and a `tools` list.
 
+The packed-tarball release smoke also checks `design-ai-mcp` after install and through one-shot `npm exec`, so package releases catch missing bin shims or broken stdio startup before publish.
+
+After publish, the public registry smoke also runs `npm exec --package @design-ai/cli@<version> -- design-ai-mcp` with the same JSON-RPC protocol checks, so npm propagation verification covers the Claude/Codex MCP entrypoint as installed by users.
+
+## Troubleshooting
+
+| Symptom | What to check |
+|---|---|
+| `/mcp` does not show `design-ai` | Confirm the command in Claude/Codex points at either `design-ai mcp` or `node /path/to/design-ai/cli/bin/design-ai-mcp.mjs`. |
+| Tool calls return `Unknown argument` | Remove unsupported fields from the MCP tool input. The server validates tool arguments before running the CLI. |
+| Tool calls return `must be an integer` or `must be a boolean` | Send JSON values with the right type, for example `{"limit": 3}` instead of `{"limit": "3"}`. |
+| Tool calls are marked `isError: true` with `[stderr]` | The MCP protocol is working; inspect the CLI error text and rerun the equivalent `design-ai ...` command locally. |
+
 ## References
 
 - [Model Context Protocol specification](https://modelcontextprotocol.io/specification/2025-11-25)

package/docs/integrations/vscode-walkthrough.ko.md

@@ -10,9 +10,9 @@ git clone https://github.com/sungjin9288/design-ai.git ~/dev/design-ai && cd ~/d
 
 # public publish 이후에는 npm/Homebrew 설치 경로로 local clone을 대체할 수 있어요.
 
-# VS Code 확장 설치 (Marketplace publish 이후)
-# code --install-extension sungjin.design-ai-vscode
-# 또는 개발 중에는 .vsix 사이드로드
+# 공개 VS Code 확장 설치
+code --install-extension sungjin.design-ai-vscode
+# 또는 로컬 확장 개발 중에는 .vsix 사이드로드
 ```
 
 ## 설치 (60초)

package/docs/integrations/vscode-walkthrough.md

@@ -10,9 +10,9 @@ git clone https://github.com/sungjin9288/design-ai.git ~/dev/design-ai && cd ~/d
 
 # After public publish, npm/Homebrew install paths can replace the local clone.
 
-# Install VS Code extension (after Marketplace publish)
-# code --install-extension sungjin.design-ai-vscode
-# Or sideload from .vsix during development
+# Install the public VS Code extension
+code --install-extension sungjin.design-ai-vscode
+# Or sideload from .vsix during local extension development
 ```
 
 ## Setup (60 seconds)

package/docs/site-overrides/main.html

@@ -10,7 +10,7 @@
   {{ super() }}
   <meta name="description" content="A model-agnostic design knowledge base + skill system. Senior product designer for any AI coding agent. 92 knowledge files covering UI/UX, website improvement, design systems, motion, illustration, print, video, game UI, conversational, and spatial design. Korean market depth.">
   <meta property="og:title" content="design-ai — Senior product designer for any AI coding agent">
-  <meta property="og:description" content="92 knowledge files, 223 worked examples, 20 skills, 17 commands. Korean market depth across all domains. Open-source MIT.">
+  <meta property="og:description" content="92 knowledge files, 221 worked examples, 20 skills, 17 commands. Korean market depth across all domains. Open-source MIT.">
   <meta property="og:type" content="website">
   <meta name="twitter:card" content="summary">
   <meta name="twitter:title" content="design-ai">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design-ai/cli",
-  "version": "4.55.0",
+  "version": "4.56.0",
   "description": "Senior product designer for any AI coding agent. Installs design-ai (20 skills, 17 commands, 4 agents) into Claude Code globally. Korean market depth plus website improvement control tower.",
   "bin": {
     "design-ai": "cli/bin/design-ai.mjs",

package/tools/audit/package-smoke.py

@@ -50,6 +50,7 @@ from smoke_assertions import (
     assert_check_examples_json_component_spec,
     assert_check_stdin_json_component_spec,
     assert_command_alias_output,
+    assert_design_ai_mcp_protocol_responses,
     assert_doctor_json_clean,
     assert_doctor_strict_output,
     assert_examples_human_output,
@@ -135,6 +136,7 @@ from smoke_assertions import (
     format_cmd,
     help_alias_script,
     help_topic_script,
+    mcp_smoke_input,
     passing_doctor_report_json,
     passing_check_artifact_content,
     passing_site_mcp_check_probes_human,
@@ -379,6 +381,18 @@ def npm_exec_cmd(tarball: Path, *args: str) -> list[str]:
     ]
 
 
+def npm_exec_mcp_cmd(tarball: Path) -> list[str]:
+    return [
+        "npm",
+        "exec",
+        "--yes",
+        "--package",
+        str(tarball),
+        "--",
+        "design-ai-mcp",
+    ]
+
+
 def npm_exec_shell_cmd(tarball: Path, script: str) -> list[str]:
     return [
         "npm",
@@ -533,6 +547,52 @@ def require_package_smoke(condition: bool, *, context: str, cmd: list[str], mess
         fail_package_smoke(context, cmd, message)
 
 
+def assert_design_ai_mcp_protocol_smoke(
+    cmd: list[str],
+    *,
+    env: dict[str, str],
+    cwd: Path | None,
+    context: str,
+) -> None:
+    print(f"$ {format_cmd(cmd)} < MCP smoke", flush=True)
+    result = subprocess.run(
+        cmd,
+        cwd=cwd,
+        env=env,
+        input=mcp_smoke_input(),
+        text=True,
+        capture_output=True,
+        timeout=15,
+    )
+    if result.stdout:
+        print(result.stdout, end="")
+    if result.stderr:
+        print(result.stderr, end="", file=sys.stderr)
+
+    if is_npm_exec_cache_enoent(cmd, result):
+        result = retry_npm_exec_once(cmd, cwd=cwd, env=env, input_text=mcp_smoke_input())
+        if result.stdout:
+            print(result.stdout, end="")
+        if result.stderr:
+            print(result.stderr, end="", file=sys.stderr)
+
+    if result.returncode != 0:
+        raise SystemExit(f"command failed with exit code {result.returncode}: {format_cmd(cmd)}")
+
+    output = f"{result.stdout}\n{result.stderr}"
+    assert_no_ansi(output, cmd)
+
+    responses = []
+    for line in result.stdout.splitlines():
+        if not line.strip():
+            continue
+        try:
+            responses.append(json.loads(line))
+        except json.JSONDecodeError as error:
+            fail_package_smoke(context, cmd, f"MCP stdout line is not JSON: {error}")
+    assert_design_ai_mcp_protocol_responses(responses, context=context, cmd=cmd)
+
+
 def run_expected_failure(
     cmd: list[str],
     *,
@@ -12482,6 +12542,37 @@ def run_self_test() -> None:
         site_bundle_mcp_probes_payload,
         context=f"{context} site bundle mcp-probes.json",
     )
+    mcp_protocol_cmd = ["design-ai-mcp"]
+    assert_design_ai_mcp_protocol_responses(
+        [
+            {"jsonrpc": "2.0", "id": 1, "result": {"serverInfo": {"name": "design-ai"}}},
+            {"jsonrpc": "2.0", "id": 2, "result": {"tools": [{"name": "design_ai_route"}, {"name": "design_ai_search"}]}},
+            {
+                "jsonrpc": "2.0",
+                "id": 3,
+                "error": {"code": -32602, "message": "design_ai_search.limit must be an integer"},
+            },
+        ],
+        context=f"{context} design-ai MCP protocol",
+        cmd=mcp_protocol_cmd,
+    )
+    expect_self_test_failure(
+        lambda: assert_design_ai_mcp_protocol_responses(
+            [
+                {"jsonrpc": "2.0", "id": 1, "result": {"serverInfo": {"name": "design-ai"}}},
+                {"jsonrpc": "2.0", "id": 2, "result": {"tools": [{"name": "design_ai_route"}, {"name": "design_ai_search"}]}},
+                {
+                    "jsonrpc": "2.0",
+                    "id": 3,
+                    "error": {"code": -32602, "message": "wrong validation message"},
+                },
+            ],
+            context=f"{context} design-ai MCP protocol",
+            cmd=mcp_protocol_cmd,
+        ),
+        expected="MCP invalid argument response did not preserve invalid params validation",
+        scope="package smoke",
+    )
     for label in (
         "site bundle check",
         "site bundle check summary",
@@ -19602,6 +19693,9 @@ def smoke_tarball(tarball: Path) -> None:
         bin_path = install_root / "node_modules" / ".bin" / "design-ai"
         if not bin_path.exists():
             raise SystemExit(f"design-ai bin shim not found: {bin_path}")
+        mcp_bin_path = install_root / "node_modules" / ".bin" / "design-ai-mcp"
+        if not mcp_bin_path.exists():
+            raise SystemExit(f"design-ai-mcp bin shim not found: {mcp_bin_path}")
 
         smoke_env = base_env.copy()
         smoke_env.update({
@@ -19620,6 +19714,12 @@ def smoke_tarball(tarball: Path) -> None:
             env=smoke_env,
             context="package smoke installed bin version JSON",
         )
+        assert_design_ai_mcp_protocol_smoke(
+            [str(mcp_bin_path)],
+            cwd=install_root,
+            env=smoke_env,
+            context="package smoke installed bin design-ai-mcp protocol",
+        )
         assert_workspace_json_smoke(
             [str(bin_path), "workspace", "--json"],
             cwd=install_root,
@@ -20999,6 +21099,12 @@ def smoke_tarball(tarball: Path) -> None:
             env=npx_env,
             context="package smoke npm exec version JSON",
         )
+        assert_design_ai_mcp_protocol_smoke(
+            npm_exec_mcp_cmd(tarball),
+            cwd=npx_root,
+            env=npx_env,
+            context="package smoke npm exec design-ai-mcp protocol",
+        )
         assert_workspace_json_smoke(
             npm_exec_cmd(tarball, "workspace", "--json"),
             cwd=npx_root,