litclaude-ai 0.2.2

package/README_ko-KR.md

@@ -0,0 +1,374 @@
+<p align="center"><img src="./cover.png" width="100%" /></p>
+
+<h1 align="center">LitClaude</h1>
+<p align="center">
+  <em>Claude Code 안에서 쓰는 LitClaude 스타일 워크플로우: prompt hook, litwork skill, agent, MCP, LSP helper.</em>
+</p>
+<p align="center">
+  <a href="#빠른-시작">빠른 시작</a> · <a href="#lit-사용법">LIT 사용법</a> · <a href="#명령어">명령어</a> · <a href="./README.md">English</a>
+</p>
+<p align="center">
+  <img src="https://img.shields.io/badge/npm-litclaude--ai-cb3837" />
+  <img src="https://img.shields.io/badge/version-0.2.2-2ea44f" />
+  <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
+  <img src="https://img.shields.io/badge/license-MIT-blue" />
+</p>
+
+---
+
+[English](./README.md) | **한국어**
+
+---
+
+> [!NOTE]
+> LitClaude는 prompt hook, skill, agent, MCP, LSP, LIT discipline을 위한
+> 조용한 Claude Code-native workflow package입니다. `litclaude@litclaude-ai`로
+> 설치되므로, 매번 긴 `--plugin-dir` 없이 일반 `claude` 실행에서
+> LitClaude skill과 hook을 불러올 수 있습니다.
+
+현재 checkout은 `litclaude-ai@0.2.2` 배포 준비용으로 정리되어 있습니다. 목적은
+다른 PC에서도 빠르게 설치하기 위한 개인용 package metadata를 갖추는 것입니다.
+npm package metadata를 준비했다고 해서 홍보, 공개 저장소 운영, Claude
+marketplace 등록을 의미하지는 않습니다. 새 버전 배포는 항상 별도의 명시적
+승인 후에 진행합니다. v0.2.2 release material은 v0.2.0 workflow parity work를
+보존하고, v0.2.1 readiness 위에 Dynamic workflow hardening을 추가하며,
+LitClaude 자체의 표현으로 정리되어 있습니다. npm publish가 완료됐다고
+주장하지 않습니다.
+
+## 기능
+
+- **자연스러운 Claude 실행** - 한 번 `npx`로 설치한 뒤에는 plain `claude`
+- **LIT prompt hook** - `lit`, `litwork`, `$lit-plan`, `$lit-loop` 트리거
+- **Deep interview mode** - `/deep-interview` 또는 `$deep-interview`로 넓고
+  모호한 의도를 먼저 spec으로 정리한 뒤 계획/구현으로 넘김
+- **v0.2.0 workflow parity** - package publish가 끝났다고 말하지 않으면서
+  `review-work` 5-lane review discipline과 litgoal runtime 문서를 추가
+- **v0.2.2 Dynamic workflow hardening** - 더 엄격한 subagent assignment
+  contract, `start-work-next`, context-pressure resume guidance, 정확한
+  mutated-file 감지, 강화된 `workflow-check --json` readiness check를 추가
+- **5-lane review** - `/review-work`가 goal/constraint verification,
+  hands-on QA execution, code quality, security, local-first context mining을
+  한 번에 점검
+- **Native goal guidance** - Claude Code가 `/goal` 또는 `get_goal`,
+  `create_goal`, `update_goal` 같은 goal surface를 제공하면 이를 우선
+  사용하도록 유도하고, goal tools are unavailable 상황의 fallback도 명시
+- **Litgoal CLI/state** - `plugins/litclaude/lib/litgoal/`가 durable
+  criteria, evidence, checkpoint, steering, review blocker를 `.litclaude/litgoal/`
+  아래에 기록
+- **Dynamic workflow/worktree guidance** - 크거나 병렬적인 작업은 Claude
+  Code Dynamic workflow, subagent delegation, Dynamic worktree 격리 쪽으로 유도
+- **Claude skills** - LitClaude 스타일을 더 풍부하게 옮긴 corpus:
+  `programming`, `debugging`, `refactor`, `ai-slop-remover`, `remove-ai-slops`,
+  `review-work`, `frontend-ui-ux`, `comment-checker`, `rules`, `lsp`,
+  `litgoal`, `deep-interview`, `lit-plan`, `lit-loop`, `start-work`
+- **Auxiliary workflow packs** - `programming/references`,
+  `programming/scripts`, `debugging/references`까지 포함해서 언어별,
+  런타임별 세부 지침을 보존
+- **워크플로우 agents** - planner, executor, verifier, reviewer, librarian, QA runner
+- **Local marketplace 등록** - `claude plugin details litclaude@litclaude-ai`에서 inventory 확인
+- **MCP와 LSP helper** - plugin-local stdio MCP와 TypeScript 계열 LSP doctor
+- **LitClaude HUD** - npm install 시 `pretty-claude-hud` 기반의 compact
+  Claude Code statusLine을 네온 `[🔥LITCLAUDE vX.Y.Z]` 브랜드로 자동 설정하고,
+  설치 중 눈에 잘 띄는 색상 선택, 즉시 mini-HUD 미리보기, compact context
+  bar, 낮은 사용량도 비어 보이지 않는 rate-limit bar, 더 넓은 brand accent
+  적용 범위, 간격이 있는 reset countdown을 제공
+- **안전한 uninstall** - LitClaude가 관리한 상태만 제거
+
+## 빠른 시작
+
+### 설치
+
+```bash
+npx --yes litclaude-ai install
+```
+
+interactive `npx` 설치에서는 LitClaude가 HUD brand color 후보를 더 선명한
+실제 터미널 색상으로 바로 보여주고, 선택한 accent를 Claude의 managed
+`statusLine` command에 저장합니다. animated install에서는 setup, plugin,
+marketplace, registry, cache label도 색상으로 구분해서 진행 상황을 더 쉽게
+스캔할 수 있습니다. noninteractive install은 deterministic한 plain
+`INSTALL_STEP` line을 유지합니다.
+
+현재 위치가 이 저장소 checkout이면, registry package와 같은 package name을
+가진 same-name source checkout 안에 있는 상태입니다. 이 경우
+`npx --yes litclaude-ai@0.1.11 install` 같은 이전 published build가 local
+checkout을 먼저 해석해서 `sh: litclaude-ai: command not found`로 실패할 수
+있었습니다. 이 checkout은 `node_modules/.bin` shim을 의도적으로 추적하지
+않습니다. 새 폴더에서는 일반 설치 명령이 정상 동작합니다.
+
+```bash
+cd /tmp
+npx --yes litclaude-ai@0.2.2 install
+```
+
+설치 상태를 확인합니다.
+
+```bash
+npx --yes litclaude-ai doctor
+```
+
+installer는 Claude Code의 `statusLine` command도 packaged LitClaude HUD로
+설정합니다. 색상을 제거한 예시는 다음처럼 시작합니다.
+
+```text
+[🔥LITCLAUDE v0.2.2] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+```
+
+`↻` 표시는 rate-limit reset까지 남은 시간을 짧게 보여주는 countdown입니다.
+percentage와는 한 칸 띄워서 읽기 쉽게 만들었고, 낮은 non-zero 사용량도
+partial bar glyph로 표시되어 비어 보이지 않습니다. context bar는 3칸,
+rate-limit bar는 2칸으로 줄여 Claude Code status-line 공간을 덜 차지합니다.
+Claude Code가 제공하는 epoch seconds 형태와 ISO timestamp 형태를 모두
+해석합니다.
+
+picker 없이 색상을 지정하려면 설치 전에 `LITCLAUDE_HUD_ACCENT`를
+`cyan`, `blue`, `teal`, `green`, `lavender`, `rose`, `gold`, `orange`,
+`slate`, `gray` 중 하나로 설정하세요.
+
+설치 후에는 일반적인 `claude` 명령으로 Claude Code를 실행합니다.
+
+```bash
+claude
+```
+
+### 대체 진입점
+
+```bash
+bunx litclaude-ai install
+npm install -g litclaude-ai
+litclaude install
+```
+
+현재 checkout처럼 package 이름이 같은 폴더 안에서 `npm exec`를 직접 쓸
+때는 registry package와 same-name source checkout이 섞이지 않도록 fresh
+prefix를 주는 편이 안전합니다.
+
+```bash
+npm exec --prefix "$(mktemp -d)" --yes --package litclaude-ai -- litclaude install
+```
+
+LitClaude가 관리한 설치 상태만 제거하려면 다음을 사용합니다.
+
+```bash
+npx --yes litclaude-ai uninstall
+```
+
+## 설치 방식
+
+installer는 `litclaude@litclaude-ai`를 Claude Code user plugin registry
+아래의 `~/.claude/plugins`에 등록하고 `settings.json`의 `enabledPlugins`,
+LitClaude 전용 local marketplace 항목, `known_marketplaces.json`을 함께
+기록합니다. 이 marketplace metadata가 있어야 Claude가
+`claude plugin details`에서 skill과 hook inventory를 해석합니다.
+
+격리 테스트가 필요할 때만 `CLAUDE_CONFIG_DIR=/some/path`와
+`LITCLAUDE_HOME=/some/path`를 지정하세요.
+
+## LIT 사용법
+
+설치 후에는 일반적인 `claude` 명령에서 LitClaude를 사용할 수 있습니다.
+
+```bash
+claude
+```
+
+그다음 Claude Code에 아래 프롬프트 중 하나를 입력합니다.
+
+```text
+lit
+litwork
+$lit-plan <계획이 필요한 작업>
+/lit-plan <계획이 필요한 작업>
+$lit-loop <증거 기반으로 실행할 작업>
+/lit-loop <증거 기반으로 실행할 작업>
+$deep-interview <명확화가 필요한 작업>
+/deep-interview <명확화가 필요한 작업>
+$dynamic-workflow <병렬 또는 위임할 목표>
+/dynamic-workflow <병렬 또는 위임할 목표>
+$review-work <검토할 범위>
+/review-work <검토할 범위>
+$litgoal <goal operation>
+/litgoal <goal operation>
+$start-work plans/example-plan.md
+/start-work plans/example-plan.md
+```
+
+기대 동작은 LitClaude prompt hook이 LIT route에는 `LITWORK MODE ENABLED`
+컨텍스트를 추가하고 `LitClaude lit hook active`라는 visible hook message를
+보여주는 것입니다. `/deep-interview`에는 `DEEP INTERVIEW MODE ENABLED`
+컨텍스트를 추가하고 Claude를 `/litclaude:deep-interview` /
+`Skill(deep-interview)` 쪽으로 라우팅합니다. 또한 plain `lit`는 일반 작업
+실행 전 `/litclaude:lit-loop` / `Skill(lit-loop)` semantics로 처리됩니다.
+그 뒤 skill 및 agent 지시문이 Claude를 test-first 작업, native goal 처리,
+실제 수동 QA 증거, cleanup receipt, 향후 release step의 명시적 승인 쪽으로
+유도합니다.
+
+LitClaude는 `/goal`을 대신 입력하거나 slash command text를 자동 전송하지
+않습니다. 대신 hook과 LIT skill이 run context를 보강합니다. Claude Code의
+native goal surface가 있으면 `get_goal`을 먼저 확인하고, matching active
+goal이 없을 때만 `create_goal`을 호출하며, `update_goal`은 검증 완료 또는
+진짜 blocker가 있을 때까지 미루도록 안내합니다. goal tools are unavailable,
+즉 model-facing goal tools가 이 Claude Code session에 노출되지 않은 경우에는
+로컬 evidence ledger를 기준으로 계속 진행하고, 긴 실행 전에 필요한 경우에만
+정확한 `/goal <completion condition>`를 제안합니다. 큰 독립 작업에서는
+같은 원칙을 Claude Code가 노출한 orchestration surface에 적용합니다.
+`Workflow`가 노출되면 `Workflow` tool을 호출하고, isolated edit lane이
+model-facing worktree를 필요로 하면 `EnterWorktree`를 사용합니다. CLI surface만
+가능한 새 격리 lane에서는 `claude --worktree <short-name> --tmux`를 사용합니다.
+
+v0.2.2 Dynamic workflow hardening에서 `/dynamic-workflow`는 넓은 위임 작업을
+위한 통합 bootstrap route입니다. `/goal`은 user-controlled 상태로 두고,
+model-facing goal tools가 노출되면 확인하며, 필요하면 정확한 fallback
+`/goal <completion condition>`만 제안합니다. subagent delegation은
+`prometheus-planner`, `boulder-executor`, `oracle-verifier`, `qa-runner`,
+`quality-reviewer`, `librarian-researcher`에 매핑됩니다. Child assignment는
+`TASK:`로 시작하고 `DELIVERABLE`, `SCOPE`, `VERIFY`를 포함해야 하므로, 위임된
+작업은 구체적인 산출물, 범위, 검증 경로를 갖습니다. Full QA 전에는 다음 package
+diagnostic을 실행합니다.
+
+```bash
+litclaude-ai workflow-check --json
+```
+
+긴 `$start-work` 실행이 중간에 끊기거나 compact된 뒤 새 pane에서 이어갈 때는
+checkout에서 continuation helper를 실행합니다.
+
+```bash
+litclaude-ai start-work-next --json
+```
+
+이 명령은 `.litclaude/boulder.json`과 `.litclaude/start-work/ledger.jsonl`을 읽고 active
+plan, ledger path, 첫 번째 unchecked top-level task를 출력합니다. Plan이 끝났으면
+`{"status":"idle","directive":null}`을 반환합니다.
+
+v0.2.0 workflow parity에서 `review-work`는 전용 review route입니다. 5-lane
+review는 goal/constraint verification, hands-on QA execution, code quality,
+security, local-first context mining을 포함합니다. 각 lane은
+`oracle-verifier`, `qa-runner`, `quality-reviewer`, `librarian-researcher`에
+연결되고, 증거를 모아 PASS, FAIL, NEEDS-CONTEXT verdict로 정리합니다.
+Manual-QA channels는 artifact를 남겨야 하며 tmux session, server, port,
+browser tab, temp directory는 completion 전에 cleanup receipt를 남겨야 합니다.
+
+`litgoal`은 긴 목표를 위한 durable local state route입니다. runtime은
+`plugins/litclaude/lib/litgoal/`에 있고 state는 `.litclaude/litgoal/` 아래에
+남깁니다. stale state가 checkout과 어긋나면 current docs/test reads를
+기준으로 판단합니다. 자주 쓰는 명령은 다음과 같습니다.
+
+```bash
+litclaude litgoal create-goals --brief "<brief>" --json
+litclaude litgoal record-evidence --criterion <id> --status pass --json '{"artifact":"...","cleanup":"..."}'
+litclaude litgoal checkpoint --status active --note "<progress>" --json
+litclaude litgoal steer --kind scope --note "<what changed and why>" --json
+```
+
+`record-review-blockers`는 해결되지 않은 review finding을 기록합니다.
+malformed JSON, unknown criterion, corrupt state, invalid steering kind는
+성공처럼 보이지 않고 controlled error로 실패해야 합니다.
+
+단순히 `lit`라고 입력하는 것은 hook context activation입니다. Claude Code
+history에는 별도 Skill tool invocation이 아니라 hook guidance로 보일 수
+있습니다. 명시적인 LitClaude skill activation을 보고 싶다면 namespaced
+command를 사용합니다.
+
+```text
+/litclaude:lit-loop <증거 기반으로 실행할 작업>
+/litclaude:dynamic-workflow <병렬 또는 위임할 목표>
+/litclaude:lit-plan <계획이 필요한 작업>
+/litclaude:deep-interview <명확화가 필요한 작업>
+/litclaude:review-work <검토할 범위>
+/litclaude:litgoal <goal operation>
+/litclaude:start-work plans/example-plan.md
+```
+
+이 namespaced command들은 `plugins/litclaude/commands/` 아래 실제 Claude Code
+command file로 배포됩니다. 따라서 `/litclaude:lit-loop`는 command body를 먼저
+로드하고, 이어서 대응 skill guidance를 따라가야 합니다.
+위의 짧은 slash alias도 prompt hook이 인식하며, plain `lit` loop fallback이
+아니라 대응 discipline으로 라우팅됩니다.
+
+요청이 넓거나 acceptance criteria, non-goal, decision boundary가 부족하면
+`/lit-plan` 전에 `/deep-interview`를 쓰는 것이 안전합니다.
+`deep-interview/` 아래 요구사항 artifact를 남기고, 구현은 직접 하지 않은 채
+계획 또는 실행 단계로 넘깁니다.
+
+## 명령어
+
+| 명령어 | 용도 |
+| --- | --- |
+| `npx --yes litclaude-ai install` | Claude Code plugin 설치 및 활성화 |
+| `npx --yes litclaude-ai --version` | packaged LitClaude version 출력 |
+| `npx --yes litclaude-ai doctor` | 파일, Claude validation, plugin details 검증 |
+| `npx --yes litclaude-ai path` | 설치된 Claude plugin 경로 출력 |
+| `npx --yes litclaude-ai run -- --help` | 설치 상태를 확인한 뒤 plain `claude` 실행 |
+| `npx --yes litclaude-ai update` | 현재 package version 재설치 |
+| `npx --yes litclaude-ai uninstall` | LitClaude가 관리한 설치 상태 제거 |
+
+전역 설치 없이 checkout 내부 bin을 확인할 수도 있습니다.
+
+```bash
+node bin/litclaude-ai.js --dry-run install
+node bin/litclaude-ai.js --dry-run doctor
+```
+
+## 로컬 개발
+
+이 저장소에서 바로 플러그인을 테스트할 때는 다음처럼 실행합니다.
+
+```bash
+claude --plugin-dir ./plugins/litclaude
+```
+
+Claude Code 안에서 플러그인 메타데이터를 다시 읽고 싶으면 다음 명령을
+사용합니다.
+
+```text
+/reload-plugins
+```
+
+기존 OMC/omc Claude 플러그인이 설치되어 있다면 테스트 중에는 LitClaude와
+함께 co-load하지 않는 것을 권장합니다. 로컬 checkout 테스트는
+`--plugin-dir`로 직접 로드하고, npm 설치는 사용자 홈 아래에 LitClaude가
+관리하는 local marketplace만 만듭니다. root Claude marketplace skeleton은
+저장소 checkout에 배포하지 않습니다. user-level OMC가 검증 중 `.omc/`
+상태 디렉터리를 만들더라도 LitClaude는 이를 git 및 npm package surface에서
+제외합니다.
+
+## 검증
+
+```bash
+npm test
+npm run validate:plugin
+npm run qa:tmux
+npm run qa:portable
+npm run pack:dry-run
+```
+
+`validate:plugin`과 `qa:tmux`는 로컬 검증용입니다. Claude Code가 없는
+환경에서는 smoke harness가 모호한 실패 대신 controlled skip과 version
+probe evidence를 남깁니다.
+
+## 안전 모델
+
+- Hook은 Claude Code event JSON을 stdin으로 읽고 제한된 JSON context를 반환합니다.
+- Hook은 사용자 프롬프트 텍스트를 실행하지 않습니다.
+- litwork prompt hook은 고정된 guidance를 반환하며 prompt text를 다시 echo하지 않습니다.
+- `.omc/`, `.litclaude/`, `evidence/` 같은 로컬 상태는 ignore되며 npm 패키지에 포함되지 않습니다.
+- planner agent는 read-only이며 edit tool을 갖지 않습니다.
+- MCP와 LSP helper는 local stdio command입니다.
+- 향후 publish, remote marketplace 변경, 새 package release는 모두 명시적 승인 후 진행합니다.
+
+## 프로젝트 지도
+
+| Surface | Path |
+| --- | --- |
+| CLI | `bin/litclaude-ai.js` |
+| Claude plugin | `plugins/litclaude/` |
+| Skills | `plugins/litclaude/skills/` |
+| Agents | `plugins/litclaude/agents/` |
+| Hooks | `plugins/litclaude/hooks/hooks.json` |
+| MCP | `plugins/litclaude/.mcp.json` |
+| LSP | `plugins/litclaude/.lsp.json` |
+
+영문 설명은 `README.md`, workflow migration 표는 `docs/migration.md`, 현재
+compatibility audit은 `docs/workflow-compatibility-audit.md`, release notes는
+`CHANGELOG.md`를 참고하세요.

package/RELEASE_CHECKLIST.md

@@ -0,0 +1,165 @@
+# LitClaude Release Checklist
+
+Status: `litclaude-ai@0.2.2` is the current release candidate for Dynamic workflow hardening.
+`package.json` is aligned to `0.2.2`, and
+`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.2.2`.
+
+This release carries the v0.2.2 Dynamic workflow hardening surfaces:
+`/dynamic-workflow`, `workflow-check --json`, native `/goal` fallback guidance,
+subagent delegation mapping, `start-work-next`, context-pressure resume
+guidance, precise post-edit mutated-file detection, and the v0.2.0
+`review-work` / `litgoal` workflow parity surfaces, including the litgoal
+runtime. It is the next publishable target when explicitly approved.
+
+DO NOT publish a new version of LitClaude, run `npm publish`, push release
+tags, or add a remote Claude Code marketplace entry without explicit user
+approval.
+
+This release path is for personal install convenience, not advertisement,
+public repo promotion, or a public launch campaign.
+
+Historical baseline anchors still covered by this checklist: `0.1.12` was the
+publish-recovery baseline, `0.1.13` added LIT command trigger guardrails,
+`0.1.14` added command-name HUD display, `0.1.15` introduced HUD brand color
+selection, `0.1.16` added rate-limit reset countdown and deep-interview install
+guidance, and `0.1.18` covered compact HUD bars and broader brand accent
+behavior.
+
+## Verified Locally
+
+- `npm test`
+- `npm run validate:plugin`
+- `npm run qa:tmux`
+- `npm run qa:portable`
+- `npm run pack:dry-run`
+
+## Local Checkout Use
+
+Use this track when testing from the current checkout:
+
+1. Run `npm test`.
+2. Run `npm run validate:plugin`.
+3. Run `npm run qa:tmux`.
+4. Run `node bin/litclaude-ai.js workflow-check --json`.
+5. Run `node bin/litclaude-ai.js litgoal --help`.
+6. Start Claude Code with `claude --plugin-dir ./plugins/litclaude`.
+
+No npm publication is required for this track.
+
+## v0.2.2 Dynamic Workflow Hardening Gates
+
+Before requesting publication approval, confirm these artifacts from the current
+checkout:
+
+- `package.json` version is `0.2.2`.
+- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.2.2`.
+- `plugins/litclaude/commands/dynamic-workflow.md` documents subagent delegation.
+- `node bin/litclaude-ai.js workflow-check --json` reports `status: pass`.
+- `node bin/litclaude-ai.js workflow-check --json` reports
+  `subagentReliability` and `commandHookAgreement` as true.
+- `node bin/litclaude-ai.js start-work-next --json` is available for active
+  `.litclaude/boulder.json` continuation state and returns idle when no task remains.
+- PostToolUse hook tests cover patch-shaped mutated-file extraction.
+- SessionStart hook tests cover context-pressure resume guidance.
+- `plugins/litclaude/commands/review-work.md` documents the 5-lane review.
+- `plugins/litclaude/commands/litgoal.md` documents durable goal state.
+- `plugins/litclaude/lib/litgoal/` ships the runtime CLI/state modules.
+- `node bin/litclaude-ai.js litgoal --help` prints durable state commands.
+- `npm pack --dry-run --json` includes runtime payloads and excludes local
+  `.litclaude/`, `.omc/`, and `evidence/` state.
+- `.litclaude/lit-loop/evidence/v020-red-contracts.txt` or equivalent RED evidence
+  exists for the workflow parity contracts before GREEN evidence.
+
+## Fresh Machine NPM Install Use
+
+Use this track after an approved npm package version exists:
+
+1. Run `npx --yes litclaude-ai install`.
+2. Run `npx --yes litclaude-ai doctor`.
+3. Start Claude Code with the normal `claude` command.
+
+The installer should register `litclaude@litclaude-ai` in Claude Code's user
+plugin registry, `settings.json` `enabledPlugins`, and the LitClaude-managed
+local marketplace metadata needed by `claude plugin details`. Do not ask users
+to type a generated command that shells out to `npx --yes litclaude-ai path` for
+normal npm installs.
+
+Run fresh-machine QA from a fresh directory, not from this repository checkout.
+Inside the same-name source checkout, older published builds such as
+`npx --yes litclaude-ai@0.1.11 install` could resolve the local package and
+fail with `sh: litclaude-ai: command not found`. This checkout intentionally
+does not track a `node_modules/.bin` shim. Use `cd /tmp` for the fresh directory
+scenario, or use the explicit fresh-prefix form:
+
+```bash
+npm exec --prefix "$(mktemp -d)" --yes --package litclaude-ai -- litclaude install
+```
+
+## Quiet Public NPM Package Release Or Update
+
+Use this track only when the user explicitly approves making a new package
+version installable through `npm`, `npx`, and `bunx`.
+
+1. Confirm the target package name and version with the user.
+2. Review `README.md`, `README_ko-KR.md`, `docs/migration.md`, and
+   `docs/workflow-compatibility-audit.md` for neutral release wording.
+3. Run `npm whoami` and confirm the intended npm account.
+4. Re-run the full local verification set from a clean checkout:
+   - `npm test`
+   - `npm run validate:plugin`
+   - `npm run doctor`
+   - `npm run qa:tmux`
+   - `npm run qa:portable`
+   - `npm run pack:dry-run`
+5. Inspect `npm pack --dry-run --json` and confirm package contents.
+6. Ask for explicit user approval to publish.
+7. Only after approval, perform the selected publication path in a separate,
+   auditable release step.
+
+For the current unscoped `litclaude-ai` package name, use:
+
+```bash
+npm publish
+```
+
+If the package is renamed to a scoped package such as `@scope/litclaude-ai`,
+publish it publicly with:
+
+```bash
+npm publish --access public
+```
+
+## Accidental Publish Rollback
+
+If the wrong package or version is published, stop and report the incident
+before further mutation. Depending on npm policy and timing, choose one audited
+rollback action with user approval:
+
+1. `npm deprecate <package>@<version> "<message>"`
+2. `npm unpublish <package>@<version>` only when allowed and explicitly approved
+3. Publish a corrected patch version after verification
+
+## Marketplace Boundary
+
+Local checkout testing still uses `claude --plugin-dir ./plugins/litclaude`.
+NPM installs should use the global Claude user plugin registry and normal
+`claude` launches. A root Claude marketplace file is intentionally not shipped
+because users may already have an OMC/omc marketplace or plugin installed. The
+npm installer creates a LitClaude-managed local marketplace under
+`LITCLAUDE_HOME` and registers only `litclaude-ai` in Claude's user marketplace
+metadata so skills and hooks appear in `claude plugin details`. Do not add a
+remote marketplace entry without explicit user approval. If user-level OMC
+creates `.omc/` state during validation, keep it ignored and confirm it is
+absent from the package dry-run.
+
+## Rollback
+
+If a local test load causes problems, stop Claude Code, restart without
+`claude --plugin-dir ./plugins/litclaude`, and run `/reload-plugins` in any
+remaining session that should drop the local plugin metadata.
+
+If an npm-installed LitClaude copy causes problems, run:
+
+```bash
+npx --yes litclaude-ai uninstall
+```