@design-ai/cli 4.55.0 → 4.56.0

package/docs/DISTRIBUTION.ko.md

@@ -2,11 +2,11 @@
 
 design-ai를 이 레포에서 어댑터의 Claude Code 환경으로 가져오는 방법.
 
-> 배포 상태, 2026-06-23 확인: 로컬 `npm run release:check`는 통과했고 GitHub Pages 문서는 공개 URL에서 확인됐어요. public npm과 VS Code Marketplace 배포는 아직 확인되지 않았으므로 package publish가 끝나기 전까지는 Git clone/local install 경로를 사용하세요. 자세한 내용은 [`external-status.md`](external-status.md)를 확인하세요.
+> 배포 상태, 2026-07-02 확인: 로컬 `npm run release:check`는 통과했고 GitHub Pages 문서는 공개 URL에서 확인됐으며, GitHub Release `v4.56.0`과 Homebrew formula `v4.56.0` pinning이 확인됐어요. npm은 아직 `@design-ai/cli@4.55.0`이 최신 public package이고 public registry smoke도 이 버전 기준으로 통과했어요. `v4.56.0` npm publish workflow는 `NPM_TOKEN` 인증과 package smoke까지 통과하지만, npm publish 단계에서 granular token의 Bypass 2FA가 필요하다는 `E403`으로 막혀 있어요. Bypass 2FA가 켜진 granular token으로 GitHub Secret을 교체하거나 Trusted Publishing으로 전환한 뒤 다시 실행해야 해요. `sungjin.design-ai-vscode@0.4.1`도 VS Code Marketplace Gallery API 기준으로 publish가 확인됐어요. 자세한 내용은 [`external-status.md`](external-status.md)를 확인하세요.
 
 ## 설치 경로
 
-### A. Git clone / local install (현재 추천)
+### A. Git clone / local install
 
 ```bash
 git clone https://github.com/sungjin9288/design-ai.git
@@ -17,14 +17,13 @@ cd design-ai
 소스가 작업 클론에 있어요. 업데이트는 `git pull && ./install.sh`.
 
 이 경로를 사용할 때:
-- public package publish 전에 design-ai를 사용할 때
 - upstream에 기여할 때
 - knowledge / skills를 로컬에서 수정할 때
 - publish된 release보다 최신 `main`을 추적할 때
 
-### B. NPM (public publish 이후)
+### B. NPM
 
-`@design-ai/cli`가 publish되고 `npm run registry:smoke`가 통과한 뒤에만 이 경로를 사용하세요.
+public package 설치 경로예요. `@design-ai/cli@4.55.0` publish와 public registry smoke 통과가 확인됐어요. `v4.56.0`은 GitHub Release로는 공개됐지만, npm에는 publish token 교체와 workflow 재실행이 끝난 뒤 올라가요.
 
 ```bash
 # npx로 일회성 (글로벌 설치 없음)
@@ -49,6 +48,35 @@ design-ai install
 
 검증된 tap release 이후에는 코퍼스가 Homebrew의 `libexec`에 설치되고 `design-ai` 바이너리가 PATH에 추가돼요.
 
+### D. VS Code Marketplace
+
+VS Code 확장은 `vscode-extension/`에 있어요. 공개 Marketplace publish는 수동 `Publish VS Code extension` GitHub Actions workflow로 처리해요.
+
+현재 공개 package:
+
+```text
+sungjin.design-ai-vscode@0.4.1
+```
+
+2026-06-30에 `0.4.1` listing copy correction publish run이 성공했고, propagation 이후 public Gallery API도 visible version `0.4.1`을 반환했어요.
+
+이 workflow의 기본값은 `dry_run=true`예요. 이 모드에서는 extension compile, unit test, `.vsix` packaging, workflow artifact 업로드까지만 실행하고 Marketplace publish는 하지 않아요.
+
+공개 publish 절차:
+
+1. `vscode-extension/package.json`의 Marketplace publisher id를 확인해요.
+2. Marketplace publish용 Azure DevOps Personal Access Token을 만들어요.
+   - Organization: **All accessible organizations**
+   - Scopes: **Marketplace → Manage**
+   - Expiration: 이번 release에 필요한 가장 짧은 기간
+3. 이 token을 repository secret `VSCE_PAT`로 추가해요.
+4. **Actions → Publish VS Code extension → Run workflow**에서 `dry_run=false`로 실행해요.
+5. `sungjin.design-ai-vscode` Marketplace listing이 검색되는지 확인해요.
+
+Microsoft의 현재 Marketplace publish 안내에 따르면 Azure DevOps global PAT는 2026-12-01에 retired 돼요. 이번 release handoff에는 `VSCE_PAT`를 사용하되, 그 전까지 Entra ID 기반 publish로 전환하는 계획을 잡아야 해요.
+
+2026-06-30 publish run은 `dry_run=false`로 성공했고 Marketplace Gallery API가 `sungjin.design-ai-vscode` listing 1개를 반환했으며 browser item URL도 HTTP `200`으로 확인됐어요.
+
 ## CLI 명령어
 
 ```
@@ -114,6 +142,8 @@ design-ai help [cmd|--json] 전체 또는 command별 도움말; --json으로 top
 - Packed-tarball smoke는 installed-bin과 one-shot `npm exec --package <tarball>` 경로에서 `design-ai learn --signals` learning signal registry, Markdown signal report `design-ai learn --signals --report --out learning-signals.md`, learn signals JSON `--out` file-write confirmation, `design-ai learn --signals --strict --json` strict gate, `design-ai learn --agent-backlog --report --out agent-backlog.md` focused agent backlog Markdown report, agent backlog JSON `--out` file-write confirmation, `design-ai learn --agent-backlog --strict --json` agent backlog strict gate, focused agent backlog readiness summaries, `optionalGapDetails` JSON field coverage, check index JSON field coverage, Markdown check index section coverage, check-capture optional-gap semantics, optional refresh-only runbook selection reason이 no-command refresh output을 executable handoff command가 아닌 status metadata로 다루는지도 확인하고, `design-ai learn --propose-skills` skill proposal의 human, JSON, Markdown `--report --out`, read-only review `--review-file`, read-only review-check Markdown report `design-ai learn --propose-skills --review-file skill-proposals.review.json --review-check --report --out skill-proposal-review-check.md`, read-only accepted proposal apply plan `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --json`, `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan` human apply-plan command contract summary와 `Command contract` section, read-only apply-plan Markdown report `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --report --out skill-proposal-apply-plan.md`, JSON review template `--review-template --out`, unified diff `--patch --out`, JSON `--out` output, `design-ai learn --propose-skills --min-evidence 3 --json` threshold skipping, 그리고 `design-ai learn --propose-skills --strict --json` expected-failure gate도 확인해요.
 - push 준비 시 `npm run ci:local`로 Real-CI parity를 먼저 확인하고, 의도된 `refs/` source-link warning만 허용하며 refs-only warning도 승인된 baseline을 넘지 않는지 함께 검증.
 - 패킹된 tarball을 임시 프로젝트에 설치해 packed-tarball installed-bin 경로를 smoke test하고 같은 public CLI surface를 one-shot `npm exec --package <tarball>` 경로로 다시 검증하며, human `design-ai version`과 `design-ai version --json` machine-readable version metadata, `design-ai help` top-level help 출력을 검증한 뒤 `design-ai help --json` topic catalog with probe-capable Website Console site help usage를 읽어 expected public topic/alias set을 확인하고, 모든 `design-ai help <command>` topic-specific usage 출력 및 shared Website Console site help topic example smoke assertions 및 `design-ai site website-workspace.json --next-actions --out website-next-actions.md` next-actions Markdown 도움말 예시 plus from-intake stdin help examples (`cat company-website-intake.ko.md | design-ai site --from-intake --stdin --out website-workspace.json --force`, `cat company-website-intake.ko.md | design-ai site --from-intake --stdin --next-actions --out website-next-actions.md --force`, `cat company-website-intake.ko.md | design-ai site --from-intake --stdin --tasks --out website-workspace.tasks.json --force`, `cat company-website-intake.ko.md | design-ai site --from-intake --stdin --bundle --tasks --out website-handoff-bundle`), 문서화된 help/command alias 출력, `find`, `cat`, `recommend`, `example`, `ex`, `ls`, `lint` functional alias 출력, 세 가지 `list` catalog domain의 human/JSON 출력, human/JSON `search` / `show` / `examples` 출력, route JSON 출력, route catalog 출력, route stdin 입력, 명시적 `show --lines` 출력과 `route --explain` 출력, unknown command failure, unknown help-topic failure, unknown list-domain failure, unknown search-dir failure, unknown route-id suggestion, unknown option suggestion, unknown value suggestion, numeric range failure 검증, prompt JSON 출력, prompt markdown 출력, prompt from-file 출력, prompt stdin 출력, pack JSON 출력, pack markdown 출력, pack from-file 출력, pack stdin 출력, prompt/pack 강제 `--out` overwrite와 prompt/pack `Wrote <path>` file-write confirmation, check examples 출력, check artifact 출력, check stdin 출력, check all-routes 출력, check learning capture output, human `design-ai audit --strict --quiet` 출력과 JSON `design-ai audit --strict --quiet --json` machine-readable repository-audit output, JSON `design-ai learn --feedback` output plus learn feedback `--out` file-write confirmation, JSON `design-ai learn --init` output, JSON `design-ai learn --backup` output, JSON `design-ai learn --redact` output, `design-ai learn --redact --from-file` output, `design-ai learn --redact --stdin` output, learn JSON `--out` file-write confirmation과 forced overwrite coverage, JSON `design-ai learn --verify` output과 learn verify `--out` file-write confirmation, JSON `design-ai learn --restore` preview/apply output과 learn restore `--out` file-write confirmation, learn restore rollback backup verification, learn restore `--backup-file` path coverage, design-ai learn --restore-backups restore rollback backup inventory coverage, design-ai learn --restore-backups --prune restore rollback backup pruning coverage, JSON `design-ai learn --import` dry-run/apply output과 learn import `--out` file-write confirmation, human / JSON `design-ai learn --stats` profile summary output과 learn stats `--out` file-write confirmation, query-filtered human learn list explanation and export JSON output, brief-relevant prompt/pack learning selection, prompt/pack learning usage sidecar recording, human / JSON `design-ai learn --usage` usage sidecar report plus learn usage `--out` file-write confirmation, human / JSON `design-ai learn --signals` learning signal registry plus Markdown `design-ai learn --signals --report --out learning-signals.md` signal report plus `design-ai learn --signals --strict --json` strict gate plus learn signals `--out` file-write confirmation, human / JSON `design-ai learn --propose-skills` preview-only skill proposal report plus Markdown `--report --out skill-proposals.md` review artifact plus read-only review `--review-file skill-proposals.review.json` decision join plus read-only review-file readiness check `design-ai learn --propose-skills --review-file skill-proposals.review.json --review-check --json` plus read-only review-check Markdown report `design-ai learn --propose-skills --review-file skill-proposals.review.json --review-check --report --out skill-proposal-review-check.md` plus read-only accepted proposal apply plan `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --json` plus read-only apply-plan Markdown report `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --report --out skill-proposal-apply-plan.md` plus JSON review template `--review-template --out skill-proposals.review.json` plus unified diff `--patch --out skill-proposals.patch` handoff plus learn skill proposals JSON `--out` file-write confirmation plus `design-ai learn --propose-skills --min-evidence 3 --json` threshold skipping plus `design-ai learn --propose-skills --strict --json` expected-failure gate, human / JSON `design-ai learn --eval-template` checkpoint generation plus generated checkpoint strict validation, human / JSON `design-ai learn --eval` checkpoint report plus learn eval `--out` file-write confirmation plus learn eval `--strict` failure gate, human / JSON `design-ai learn --audit` cleanup suggestion output과 learn audit `--out` file-write confirmation, human / JSON `design-ai learn --curate` archive-first curation output plus usage-aware curation JSON review, human `design-ai update --dry-run` output과 `design-ai update --dry-run --json` machine-readable update plan, fake `CLAUDE_HOME` 기반 human `design-ai install` 출력, `design-ai install --json` machine-readable install lifecycle output, `design-ai doctor --strict` human diagnostics 출력, `design-ai doctor --json` machine-readable diagnostics 출력, human `design-ai status` 출력과 JSON status, `design-ai status --json` machine-readable install-state output, human `design-ai uninstall` 출력과 `design-ai uninstall --json` machine-readable uninstall lifecycle output까지 검증.
+- 긴 package smoke를 실행하기 전에 `NPM_TOKEN` 인증을 확인해요. package-scoped granular token은 더 넓은 scope 목록 조회를 거부할 수 있어서 package-list 확인은 advisory로만 다뤄요.
+- token 기반 CI publish는 npm 정책상 interactive 2FA 또는 Bypass 2FA가 켜진 granular access token이 필요해요. 장기적으로는 package와 workflow가 지원할 때 Trusted Publishing이 더 나은 경로예요.
 - `--provenance`로 publish (npm provenance attestation).
 - publish 후 공개 npm registry package를 `npm exec --package @design-ai/cli@<version>` 경로로 smoke test하고, human version과 `design-ai version --json` machine-readable version metadata, `design-ai help` top-level help 출력, expected `design-ai help --json` catalog with probe-capable Website Console site help usage, 발견된 help topic usage 출력 및 shared Website Console site help topic example smoke assertions 및 `design-ai site website-workspace.json --next-actions --out website-next-actions.md` next-actions Markdown 도움말 예시 plus from-intake stdin help examples (`cat company-website-intake.ko.md | design-ai site --from-intake --stdin --out website-workspace.json --force`, `cat company-website-intake.ko.md | design-ai site --from-intake --stdin --next-actions --out website-next-actions.md --force`, `cat company-website-intake.ko.md | design-ai site --from-intake --stdin --tasks --out website-workspace.tasks.json --force`, `cat company-website-intake.ko.md | design-ai site --from-intake --stdin --bundle --tasks --out website-handoff-bundle`), 문서화된 help/command alias 출력, `find`, `cat`, `recommend`, `example`, `ex`, `ls`, `lint` functional alias 출력, 세 가지 `list` catalog domain의 human/JSON 출력, human/JSON corpus discovery 출력, route JSON 출력, route catalog 출력, route stdin 입력, 명시적 `show --lines` 출력과 `route --explain` 출력, unknown command failure, unknown help-topic failure, unknown list-domain failure, unknown search-dir failure, unknown route-id suggestion, unknown option suggestion, unknown value suggestion, numeric range failure 검증, prompt JSON 출력, prompt markdown 출력, prompt from-file 출력, prompt stdin 출력, pack JSON 출력, pack markdown 출력, pack from-file 출력, pack stdin 출력, prompt/pack 강제 output-file과 prompt/pack file-write confirmation, check examples 출력, check artifact 출력, check stdin 출력, check all-routes 출력, check learning capture output, human `design-ai audit --strict --quiet` 출력과 JSON `design-ai audit --strict --quiet --json` machine-readable repository-audit output, public registry JSON `design-ai learn --verify` output과 public registry learn verify `--out` file-write confirmation, public registry JSON `design-ai learn --backup` output과 public registry learn backup `--out` file-write confirmation, public registry human / JSON `design-ai learn --stats` profile summary output과 public registry learn stats `--out` file-write confirmation, human `design-ai update --dry-run` output, `design-ai update --dry-run --json` machine-readable update plan, human `design-ai install` 출력과 `design-ai install --json` machine-readable install lifecycle output, `design-ai doctor --strict` human diagnostics 출력, `design-ai doctor --json` machine-readable diagnostics 출력, human `design-ai status` 출력과 JSON status, `design-ai status --json` machine-readable install-state output, human `design-ai uninstall` 출력과 `design-ai uninstall --json` machine-readable uninstall lifecycle output도 함께 검증.
 - Public registry workspace readiness coverage는 공개 npm registry `design-ai workspace --strict --json` strict 실패/성공 readiness checks를 published package path에서 확인해요.
@@ -237,7 +267,6 @@ chown -R $USER ~/.claude
 
 - **Homebrew tap → homebrew-core** — 코퍼스가 안정화되면 정식 등록.
 - **Claude Code 플러그인 마켓플레이스** — 그 생태계가 성숙하면.
-- **VS Code Marketplace publish** — 로컬 확장을 public install surface로 전환.
 - **Docker 이미지** — CI / 샌드박스 환경용.
 
 ## 교차 참조

package/docs/DISTRIBUTION.md

@@ -2,11 +2,11 @@
 
 How design-ai gets from this repo into adopters' Claude Code installations.
 
-> Distribution status, checked 2026-06-23: local `npm run release:check` passes and GitHub Pages docs are live. Public npm and VS Code Marketplace distribution are not currently confirmed, so use the Git clone/local install path until package publishing is completed. See [`external-status.md`](external-status.md).
+> Distribution status, checked 2026-07-02: local `npm run release:check` passes, GitHub Pages docs are live, GitHub Release `v4.56.0` is published, the Homebrew formula is pinned to `v4.56.0`, `@design-ai/cli@4.55.0` remains the latest public npm package with registry smoke coverage, and `sungjin.design-ai-vscode@0.4.1` is published to the VS Code Marketplace by Gallery API evidence. The `v4.56.0` npm publish workflow now authenticates `NPM_TOKEN` and passes package smoke, but npm rejects publish unless the granular token has Bypass 2FA enabled or the workflow uses Trusted Publishing. See [`external-status.md`](external-status.md).
 
 ## Install paths
 
-### A. Git clone / local install (currently recommended)
+### A. Git clone / local install
 
 ```bash
 git clone https://github.com/sungjin9288/design-ai.git
@@ -17,14 +17,13 @@ cd design-ai
 The source is your working clone. Pull updates with `git pull && ./install.sh`.
 
 Use this path if you want to:
-- Use design-ai before public package publish.
 - Contribute back upstream.
 - Modify knowledge / skills locally.
 - Track latest `main` rather than published releases.
 
-### B. NPM (after public publish)
+### B. NPM
 
-Use this path only after `@design-ai/cli` is published and `npm run registry:smoke` passes.
+Use this path for the public package. `@design-ai/cli@4.55.0` is published and public registry smoke has passed. `v4.56.0` is available as a GitHub Release, but it is not on npm until the publish token is replaced and the workflow is rerun successfully.
 
 ```bash
 # One-shot via npx (no global install)
@@ -43,6 +42,35 @@ After install, the CLI symlinks the bundled corpus into `~/.claude/skills/`, `~/
 
 For environments where neither npm nor bash works the way you expect. See [PLUGIN-PACKAGING.md](PLUGIN-PACKAGING.md) for the manual symlink loop.
 
+### D. VS Code Marketplace
+
+The VS Code extension lives in `vscode-extension/`. Public Marketplace publish is handled by the manual `Publish VS Code extension` GitHub Actions workflow.
+
+Current public package:
+
+```text
+sungjin.design-ai-vscode@0.4.1
+```
+
+The `0.4.1` listing-copy correction publish run succeeded on 2026-06-30, and the public Gallery API returned visible version `0.4.1` after propagation.
+
+The workflow defaults to `dry_run=true`, which compiles the extension, runs unit tests, packages a `.vsix`, and uploads the VSIX as a workflow artifact without publishing.
+
+To publish publicly:
+
+1. Confirm the Marketplace publisher id in `vscode-extension/package.json`.
+2. Create an Azure DevOps Personal Access Token for Marketplace publishing:
+   - Organization: **All accessible organizations**
+   - Scopes: **Marketplace → Manage**
+   - Expiration: shortest practical lifetime for this release
+3. Add that token as a repository secret named `VSCE_PAT`.
+4. Run **Actions → Publish VS Code extension → Run workflow** with `dry_run=false`.
+5. Verify the Marketplace listing for `sungjin.design-ai-vscode`.
+
+Microsoft's current Marketplace publishing guidance warns that Azure DevOps global PATs retire on 2026-12-01. Use `VSCE_PAT` for the current release handoff, then plan a migration to Entra ID based publishing before that date.
+
+The 2026-06-30 publish run completed successfully with `dry_run=false`, the Marketplace Gallery API returned one listing for `sungjin.design-ai-vscode`, and the browser item URL returned HTTP `200`.
+
 ## CLI commands
 
 ```
@@ -98,6 +126,8 @@ For releases, both must match. The publish workflow enforces this:
 The workflow:
 - Verifies tag matches `package.json` version.
 - Verifies `package.json` and `plugin.json` versions match.
+- Verifies `NPM_TOKEN` can authenticate before the long package smoke runs; package-list access is advisory because package-scoped granular tokens can refuse broader scope listing.
+- For token-based CI publish, npm requires either an interactive 2FA flow or a granular access token with Bypass 2FA enabled. Trusted Publishing is the preferred long-term path when it is available for the package/workflow.
 - Runs `npm run audit:strict` for all 8 audits (frontmatter / link / Korean copy / raw hex / integration / stale / coverage / example QA).
 - Runs `npm test` CLI unit tests before publishing or attaching release assets.
 - Runs whitespace checks with `git diff --check` before packaging.
@@ -209,11 +239,8 @@ Adopters can download the tarball, extract it, and run `./install.sh` directly.
 
 Possibilities (not yet implemented):
 
-- **Homebrew tap** — `brew install design-ai`
 - **Claude Code plugin marketplace** — once that ecosystem matures, list there
-- **VS Code Marketplace publish** — move the local extension wrapper to a public install surface
 - **Docker image** — for CI / sandboxed environments
-- **Public doc site** (mkdocs / docusaurus) — for browsing knowledge without install
 
 ## Troubleshooting
 

package/docs/RELEASE-CHECKLIST.md

@@ -191,6 +191,7 @@ After the tag is live:
 - [ ] Verify public install path: `npm run registry:smoke`
 - [ ] Verify doc site updated: visit deployed URL
 - [ ] If breaking change in major version: update Homebrew formula sha256 + version.
+- [ ] If publishing the VS Code extension: run `Publish VS Code extension` with `dry_run=true`, then re-run with `dry_run=false` after `VSCE_PAT` is configured.
 - [ ] Optional: GitHub release notes (auto-generated from CHANGELOG.md section).
 
 ## For major versions (vN.0.0)
@@ -229,11 +230,27 @@ Walk through all knowledge files with `stability: experimental` or `stability: b
 
 Separate from npm:
 
+1. Confirm `vscode-extension/package.json` has the correct `publisher` and `version`.
+2. Create an Azure DevOps Personal Access Token for Marketplace publishing:
+   - Organization: **All accessible organizations**
+   - Scopes: **Marketplace → Manage**
+   - Expiration: shortest practical lifetime for this release
+3. Add that token as repository secret `VSCE_PAT`.
+4. Run **Actions → Publish VS Code extension → Run workflow** with `dry_run=true`.
+5. Inspect the uploaded VSIX artifact.
+6. Re-run the same workflow with `dry_run=false` to publish.
+7. Verify the `sungjin.design-ai-vscode` Marketplace listing.
+
+If `vsce publish` returns 401/403, first check that the token was created with **All accessible organizations** and **Marketplace → Manage**. Microsoft's current guidance also warns that Azure DevOps global PATs retire on 2026-12-01, so migrate this workflow to Entra ID based publishing before that date.
+
+Local equivalent for package-only validation:
+
 ```bash
 cd vscode-extension
-npm install
-npx @vscode/vsce package        # produces .vsix
-npx @vscode/vsce publish        # requires Azure DevOps PAT + publisher account
+npm ci --no-audit --no-fund
+npm run compile
+npm test
+npx --yes @vscode/vsce@latest package --out /tmp/design-ai-vscode-$(node -p "require('./package.json').version").vsix
 ```
 
 Publisher account setup: <https://code.visualstudio.com/api/working-with-extensions/publishing-extension>