@design-ai/cli 4.55.0

package/docs/COMPANY-WEBSITE-DOGFOOD.ko.md

@@ -0,0 +1,144 @@
+# 회사 웹사이트 Dogfood Runbook
+
+실제 회사 웹사이트에 `design-ai`를 처음 적용할 때 이 runbook을 사용합니다. 목표는 이 repo에서 검증된 Website Improvement handoff bundle을 만들고, 생성된 구현 프롬프트를 대상 웹사이트 repo 안에서 실행하는 것입니다.
+
+이 repo는 계획과 handoff control tower 역할만 합니다. 대상 웹사이트 소스 코드를 이 repo로 복사하지 않습니다.
+
+## 필수 Intake
+
+첫 bundle을 만들기 전에 아래 값을 모읍니다.
+
+사이트 정보가 아직 정리되지 않았다면 [회사 웹사이트 Intake Template](COMPANY-WEBSITE-INTAKE-TEMPLATE.ko.md)을 먼저 채웁니다.
+
+| 항목 | 필수 | 예시 |
+|---|---:|---|
+| 사이트 이름 | 예 | `Company marketing site` |
+| Live URL | 예 | `https://www.example.com` |
+| 대상 repo URL 또는 local path | 예 | `https://github.com/company/site` 또는 `/Users/me/work/site` |
+| 우선순위 페이지 | 예 | `/`, `/pricing`, `/contact` |
+| 주요 사용자 흐름 | 예 | `방문자가 요금제를 비교하고 데모를 요청한다` |
+| Figma URL | 선택 | `https://www.figma.com/file/...` |
+| 배포 플랫폼 | 선택 | `vercel`, `netlify`, `cloudflare`, `other`, `none` |
+| CMS / DB / Sentry 메모 | 선택 | `Sanity`, `Supabase`, `Sentry project slug` |
+| 브랜드 제약 | 선택 | 톤, 타이포그래피, 컬러, 법무 문구, 한국어 카피 규칙 |
+
+## 1단계: Workspace와 Bundle 생성
+
+`design-ai` repo에서 실행합니다.
+
+intake template을 이미 작성했다면 먼저 workspace로 변환합니다.
+
+```bash
+design-ai site --from-intake company-website-intake.ko.md --out website-workspace.json --force
+design-ai site --from-intake company-website-intake.ko.md --next-actions --out website-next-actions.md --force
+```
+
+intake 파일이 아직 없다면 direct `--init` field를 사용합니다.
+
+```bash
+design-ai site --init \
+  --name "Company marketing site" \
+  --live-url https://www.example.com \
+  --repo-url https://github.com/company/site \
+  --page / \
+  --page /pricing \
+  --page /contact \
+  --flow "Visitor compares plans and requests a demo" \
+  --next-actions \
+  --out website-next-actions.md
+```
+
+이어서 portable handoff bundle을 생성합니다.
+
+```bash
+design-ai site --from-intake company-website-intake.ko.md \
+  --bundle \
+  --out website-handoff-bundle \
+  --strict \
+  --force
+```
+
+또는 direct field로 bundle을 생성합니다.
+
+```bash
+design-ai site --init \
+  --name "Company marketing site" \
+  --live-url https://www.example.com \
+  --repo-url https://github.com/company/site \
+  --page / \
+  --page /pricing \
+  --page /contact \
+  --flow "Visitor compares plans and requests a demo" \
+  --bundle \
+  --out website-handoff-bundle \
+  --strict
+```
+
+대상 repo가 이미 로컬에 clone되어 있다면 `--repo-url`보다 `--local-path /absolute/path/to/site`를 우선 사용합니다.
+
+## 2단계: Target Repo 작업 전 Bundle 검증
+
+```bash
+design-ai site website-handoff-bundle --bundle-check --strict --json --out website-bundle-check.json
+design-ai site website-handoff-bundle --bundle-handoff --strict --out target-repo-handoff.md
+```
+
+`bundle-check`가 통과해야 구현으로 넘어갑니다. handoff prompt에는 아래 항목이 반드시 포함되어야 합니다.
+
+- target repo 확인 규칙
+- architecture와 design system 사전 점검
+- 한 번에 하나의 focused task 범위
+- target repo에서 실행할 quality gate 명령
+- 구현 evidence와 remaining risk 기록 요구사항
+
+## 3단계: 대상 웹사이트 Repo에서 실행
+
+대상 웹사이트 repo를 Codex 또는 Claude Code로 열고 `target-repo-handoff.md`를 붙여넣습니다.
+
+구현 agent는 반드시 아래 순서를 지킵니다.
+
+1. 대상 repo path와 현재 branch를 확인합니다.
+2. 수정 전에 framework, routing, styling, component, design token 구조를 점검합니다.
+3. 넓은 redesign이 아니라 하나의 focused refactor task만 적용합니다.
+4. 대상 repo의 관련 검증을 실행합니다: lint, typecheck, tests, build, browser smoke, deployment preview verification.
+5. 변경 파일, 검증 결과, 필요한 screenshot, 남은 risk, 다음 추천 task를 반환합니다.
+
+## 4단계: Evidence를 design-ai로 회수
+
+target repo 구현 뒤 evidence를 Website Improvement Console 또는 workspace JSON에 다시 기록합니다.
+
+| Evidence 영역 | 기록할 내용 |
+|---|---|
+| 실행한 작업 | 변경된 페이지/컴포넌트, commit/PR 링크, scope 결정 |
+| 검증 결과 | 실행한 명령, pass/fail 상태, browser 또는 deployment smoke 메모 |
+| 남은 리스크 | 검증하지 못한 항목, production data dependency, 남은 접근성/SEO 이슈 |
+| 다음 작업 | 다음 task 후보와 우선순위 이유 |
+
+그다음 report를 다시 생성합니다.
+
+```bash
+design-ai site website-workspace.json --report --out website-handoff.md --force
+design-ai site website-workspace.json --bundle --out website-handoff-bundle.after --strict
+design-ai site website-handoff-bundle --bundle-compare website-handoff-bundle.after --strict --json
+```
+
+## Stop Conditions
+
+아래 조건에서는 구현 전에 멈춥니다.
+
+- 대상 repo path가 불명확합니다.
+- Live URL이 열리지 않거나 다른 사이트를 가리킵니다.
+- `--strict` bundle check가 실패합니다.
+- required MCP readiness가 `unavailable`인데 수동 fallback이 없습니다.
+- 대상 repo에 실행 가능한 검증 명령도, 수동 smoke 경로도 없습니다.
+- 요청 변경이 credential, production write, destructive migration 승인을 필요로 합니다.
+
+## 첫 Pilot 완료 기준
+
+첫 회사 dogfood는 아래 조건이 모두 충족될 때 완료입니다.
+
+- 검증된 `website-handoff-bundle`이 존재합니다.
+- `target-repo-handoff.md`가 실제 target repo 안에서 사용됐습니다.
+- 하나의 focused improvement task가 구현되고 검증됐습니다.
+- evidence가 Website Improvement workspace로 다시 기록됐습니다.
+- 최종 `website-handoff.md` report에 변경 사항, 통과한 검증, 남은 risk, 다음 작업이 기록됐습니다.

package/docs/COMPANY-WEBSITE-DOGFOOD.md

@@ -0,0 +1,150 @@
+# Company Website Dogfood Runbook
+
+Use this runbook when applying `design-ai` to a real company website for the first internal pilot. The goal is to create a verified Website Improvement handoff bundle in this repository, then execute the generated implementation prompt inside the target website repository.
+
+This repository remains the planning and handoff control tower. Do not copy the target website source code into this repository.
+
+## Required Intake
+
+Collect these values before generating the first bundle:
+
+Use the [Company Website Intake Template](COMPANY-WEBSITE-INTAKE-TEMPLATE.md) when the site details are not ready yet.
+
+| Field | Required | Example |
+|---|---:|---|
+| Site name | yes | `Company marketing site` |
+| Live URL | yes | `https://www.example.com` |
+| Target repo URL or local path | yes | `https://github.com/company/site` or `/Users/me/work/site` |
+| Priority pages | yes | `/`, `/pricing`, `/contact` |
+| Primary user flows | yes | `Visitor compares plans and requests a demo` |
+| Figma URL | optional | `https://www.figma.com/file/...` |
+| Deploy provider | optional | `vercel`, `netlify`, `cloudflare`, `other`, `none` |
+| CMS / DB / Sentry notes | optional | `Sanity`, `Supabase`, `Sentry project slug` |
+| Brand constraints | optional | Tone, typography, color, legal copy, Korean copy rules |
+
+## Step 1: Generate The Workspace And Bundle
+
+Run this from the `design-ai` repository:
+
+If the intake template is already filled, convert it first:
+
+```bash
+design-ai site --from-intake company-website-intake.md --out website-workspace.json --force
+design-ai site --from-intake company-website-intake.md --next-actions --out website-next-actions.md --force
+design-ai site --from-intake company-website-intake.md --tasks --out website-workspace.tasks.json --force
+design-ai site --from-intake company-website-intake.md --bundle --tasks --out website-handoff-bundle --strict --force
+```
+
+Use direct `--init` fields when no intake file exists yet:
+
+```bash
+design-ai site --init \
+  --name "Company marketing site" \
+  --live-url https://www.example.com \
+  --repo-url https://github.com/company/site \
+  --page / \
+  --page /pricing \
+  --page /contact \
+  --flow "Visitor compares plans and requests a demo" \
+  --next-actions \
+  --out website-next-actions.md
+```
+
+Then create the portable handoff bundle:
+
+```bash
+design-ai site --from-intake company-website-intake.md \
+  --bundle \
+  --tasks \
+  --out website-handoff-bundle \
+  --strict \
+  --force
+```
+
+Or create it from direct fields:
+
+```bash
+design-ai site --init \
+  --name "Company marketing site" \
+  --live-url https://www.example.com \
+  --repo-url https://github.com/company/site \
+  --page / \
+  --page /pricing \
+  --page /contact \
+  --flow "Visitor compares plans and requests a demo" \
+  --bundle \
+  --out website-handoff-bundle \
+  --strict
+```
+
+If the target repo is already cloned locally, prefer `--local-path /absolute/path/to/site` instead of `--repo-url`.
+
+## Step 2: Verify The Bundle Before Target Repo Work
+
+```bash
+design-ai site website-handoff-bundle --bundle-check --strict --json --out website-bundle-check.json
+design-ai site website-handoff-bundle --bundle-handoff --strict --out target-repo-handoff.md
+design-ai site website-handoff-bundle --bundle-handoff --task 1 --strict --out target-repo-task-accessibility-handoff.md
+```
+
+The bundle is ready for implementation only when `bundle-check` passes. The handoff prompt must carry:
+
+- target repo confirmation rules
+- architecture and design-system inspection requirements
+- focused task scope
+- quality gate commands to run in the target repo
+- implementation evidence and remaining-risk requirements
+
+Use the plain `--bundle-handoff` command when the top-priority bundled implementation prompt is correct. The generated handoff now includes an “Available Bundle Tasks” catalog with each task number, id, priority, impact, effort, pages, recommended MCPs, and a copy-ready strict handoff command. JSON output exposes that top-priority choice as `bundle.defaultTask` and the actual prompt target as `bundle.effectiveTask`. Add `--task <id-or-number>` when the company pilot has chosen a specific task from that catalog or from `website-workspace.tasks.json`; JSON output also includes the selected task's own `handoffOutFile`, `handoffCommand`, and `strictHandoffCommand`, while `bundle.effectiveTask` switches to that selected task.
+
+## Step 3: Execute In The Target Website Repo
+
+Open the target website repository in Codex or Claude Code and paste `target-repo-handoff.md` or the task-selected `target-repo-task-accessibility-handoff.md`.
+
+The implementation agent must:
+
+1. Confirm the target repo path and current branch.
+2. Inspect the existing framework, routing, styling, components, and design tokens before editing.
+3. Apply one focused refactor task, not a broad redesign.
+4. Run the target repo's relevant checks: lint, typecheck, tests, build, browser smoke, or deployment preview verification.
+5. Return changed files, verification output, screenshots when relevant, remaining risks, and the next recommended task.
+
+## Step 4: Record Evidence Back In design-ai
+
+After target repo implementation, copy the evidence back into the Website Improvement Console or workspace JSON:
+
+| Evidence area | What to record |
+|---|---|
+| Executed work | Changed pages/components, commit/PR link, scope decisions |
+| Verification results | Commands run, pass/fail status, browser or deployment smoke notes |
+| Remaining risks | Items not verified, production data dependencies, unresolved accessibility or SEO findings |
+| Next actions | The next task candidate and why it should come next |
+
+Then regenerate the report:
+
+```bash
+design-ai site website-workspace.json --report --out website-handoff.md --force
+design-ai site website-workspace.json --bundle --out website-handoff-bundle.after --strict
+design-ai site website-handoff-bundle --bundle-compare website-handoff-bundle.after --strict --json
+```
+
+## Stop Conditions
+
+Stop before implementation if any of these are true:
+
+- The target repo path is unclear.
+- The live URL is unavailable or points at the wrong site.
+- The bundle check fails under `--strict`.
+- Required MCP readiness is marked `unavailable` without a manual fallback.
+- The target repo has no runnable verification command and no manual smoke path.
+- The requested change requires credentials, production writes, or destructive migration approval.
+
+## First Pilot Definition Of Done
+
+The first company dogfood pass is complete when:
+
+- A verified `website-handoff-bundle` exists.
+- `target-repo-handoff.md` has been used inside the real target repo.
+- One focused improvement task is implemented and verified.
+- Evidence is copied back into the Website Improvement workspace.
+- A final `website-handoff.md` report records what changed, what passed, what remains risky, and what should happen next.

package/docs/COMPANY-WEBSITE-INTAKE-TEMPLATE.ko.md

@@ -0,0 +1,153 @@
+# 회사 웹사이트 Intake Template
+
+첫 Website Improvement dogfood 전에 이 template을 채웁니다. 민감한 credential, private token, production secret, 고객 데이터는 이 문서에 적지 않습니다.
+
+## Site Profile
+
+| 항목 | 값 |
+|---|---|
+| 사이트 이름 | |
+| Live URL | |
+| 대상 repo URL | |
+| 대상 repo local path | |
+| Figma URL | |
+| 배포 플랫폼 | `vercel` / `netlify` / `cloudflare` / `other` / `none` |
+| Sentry 프로젝트 | |
+| CMS | `sanity` / `contentful` / `wordpress` / `shopify` / `none` / `other` |
+| Database | `supabase` / `neon` / `postgres` / `none` / `other` |
+
+## 우선순위 페이지
+
+첫 pilot에서는 2-5개 페이지를 고릅니다. 전환, 신뢰, 가입, 문의, 구매, 온보딩에 영향을 주는 페이지부터 시작합니다.
+
+| 우선순위 | Path 또는 URL | 중요한 이유 |
+|---:|---|---|
+| 1 | `/` | |
+| 2 | | |
+| 3 | | |
+| 4 | | |
+| 5 | | |
+
+## 주요 사용자 흐름
+
+| 우선순위 | Flow | 성공 신호 |
+|---:|---|---|
+| 1 | | |
+| 2 | | |
+| 3 | | |
+
+## Brand And Content Notes
+
+| 영역 | 메모 |
+|---|---|
+| 브랜드 톤 | |
+| 타이포그래피 제약 | |
+| 컬러 제약 | |
+| 한국어 카피 규칙 | |
+| 법무 또는 compliance 문구 | |
+| 신뢰 요소 | |
+| 경쟁사 또는 레퍼런스 | |
+
+## MCP Readiness Notes
+
+각 외부 시스템을 `required`, `optional`, `unused`, `unavailable` 중 하나로 표시합니다.
+
+| 시스템 | 상태 | 근거 또는 fallback |
+|---|---|---|
+| GitHub | | |
+| Figma | | |
+| Browser / Playwright | | |
+| Chrome DevTools | | |
+| 배포 플랫폼 | | |
+| Sentry | | |
+| Database | | |
+| CMS | | |
+| 협업 도구 | | |
+| 리서치 도구 | | |
+
+## 초기 Audit Findings
+
+실제로 확인한 finding만 기록합니다. Lighthouse, axe, crawler, analytics를 실제로 실행하지 않았다면 해당 결과를 만들어 쓰지 않습니다.
+
+| Category | Finding | Evidence | Page |
+|---|---|---|---|
+| Visual design | | | |
+| UX flow | | | |
+| Responsive | | | |
+| Accessibility | | | |
+| Performance | | | |
+| SEO | | | |
+| Technical quality | | | |
+| Runtime issues | | | |
+| Content quality | | | |
+
+## 첫 Bundle Commands
+
+placeholder를 바꾼 뒤 `design-ai` repo에서 실행합니다.
+
+이 intake 파일을 채웠다면 그대로 사용합니다.
+
+```bash
+design-ai site --from-intake company-website-intake.ko.md --out website-workspace.json --force
+design-ai site --from-intake company-website-intake.ko.md --next-actions --out website-next-actions.md --force
+design-ai site --from-intake company-website-intake.ko.md --bundle --out website-handoff-bundle --strict --force
+```
+
+intake 파일이 없다면 direct field를 사용합니다.
+
+```bash
+design-ai site --init \
+  --name "<site name>" \
+  --live-url <live-url> \
+  --local-path <absolute-target-repo-path> \
+  --page / \
+  --page <priority-page-2> \
+  --flow "<primary user flow>" \
+  --next-actions \
+  --out website-next-actions.md \
+  --force
+```
+
+```bash
+design-ai site --init \
+  --name "<site name>" \
+  --live-url <live-url> \
+  --local-path <absolute-target-repo-path> \
+  --page / \
+  --page <priority-page-2> \
+  --flow "<primary user flow>" \
+  --bundle \
+  --out website-handoff-bundle \
+  --strict \
+  --force
+```
+
+```bash
+design-ai site website-handoff-bundle --bundle-check --strict --json --out website-bundle-check.json --force
+design-ai site website-handoff-bundle --bundle-handoff --strict --out target-repo-handoff.md --force
+```
+
+## Target Repo Verification Plan
+
+구현 전에 채워서 target-repo agent가 명확한 quality gate를 갖게 합니다.
+
+| Gate | 명령 또는 수동 확인 | Pilot 필수 |
+|---|---|---:|
+| Install | | 예 |
+| Lint | | 예 |
+| Typecheck | | 가능하면 |
+| Unit tests | | 가능하면 |
+| Build | | 예 |
+| Browser smoke | | 예 |
+| Accessibility spot check | | 예 |
+| Deployment preview | | 가능하면 |
+
+## Stop Conditions
+
+아래 질문 중 하나라도 불명확하면 target repo 수정 전에 멈춥니다.
+
+- 어떤 repo와 branch를 수정해야 하는가?
+- 첫 번째로 구현할 single task는 무엇인가?
+- 어떤 verification command가 반드시 통과해야 하는가?
+- 어떤 credential 또는 production system이 off limits인가?
+- target-repo pass 이후 implementation evidence를 어디에 기록해야 하는가?

package/docs/COMPANY-WEBSITE-INTAKE-TEMPLATE.md

@@ -0,0 +1,154 @@
+# Company Website Intake Template
+
+Fill this template before the first Website Improvement dogfood pass. Keep sensitive credentials, private tokens, production secrets, and customer data out of this document.
+
+## Site Profile
+
+| Field | Value |
+|---|---|
+| Site name | |
+| Live URL | |
+| Target repo URL | |
+| Target repo local path | |
+| Figma URL | |
+| Deploy provider | `vercel` / `netlify` / `cloudflare` / `other` / `none` |
+| Sentry project | |
+| CMS | `sanity` / `contentful` / `wordpress` / `shopify` / `none` / `other` |
+| Database | `supabase` / `neon` / `postgres` / `none` / `other` |
+
+## Priority Pages
+
+List 2-5 pages for the first pilot. Start with pages that affect conversion, trust, signup, inquiry, purchase, or onboarding.
+
+| Priority | Path or URL | Why it matters |
+|---:|---|---|
+| 1 | `/` | |
+| 2 | | |
+| 3 | | |
+| 4 | | |
+| 5 | | |
+
+## Primary User Flows
+
+| Priority | Flow | Success signal |
+|---:|---|---|
+| 1 | | |
+| 2 | | |
+| 3 | | |
+
+## Brand And Content Notes
+
+| Area | Notes |
+|---|---|
+| Brand tone | |
+| Typography constraints | |
+| Color constraints | |
+| Korean copy rules | |
+| Legal or compliance copy | |
+| Trust signals | |
+| Competitors or references | |
+
+## MCP Readiness Notes
+
+Mark each external system as `required`, `optional`, `unused`, or `unavailable`.
+
+| System | Status | Evidence or fallback |
+|---|---|---|
+| GitHub | | |
+| Figma | | |
+| Browser / Playwright | | |
+| Chrome DevTools | | |
+| Deploy provider | | |
+| Sentry | | |
+| Database | | |
+| CMS | | |
+| Collaboration tool | | |
+| Research tool | | |
+
+## Initial Audit Findings
+
+Capture only findings that are grounded in inspection. Do not invent Lighthouse, axe, crawler, or analytics results unless those tools were actually run in the target repo or browser.
+
+| Category | Finding | Evidence | Page |
+|---|---|---|---|
+| Visual design | | | |
+| UX flow | | | |
+| Responsive | | | |
+| Accessibility | | | |
+| Performance | | | |
+| SEO | | | |
+| Technical quality | | | |
+| Runtime issues | | | |
+| Content quality | | | |
+
+## First Bundle Commands
+
+Replace placeholders and run from the `design-ai` repository.
+
+If this intake file is filled, use it directly:
+
+```bash
+design-ai site --from-intake company-website-intake.md --out website-workspace.json --force
+design-ai site --from-intake company-website-intake.md --next-actions --out website-next-actions.md --force
+design-ai site --from-intake company-website-intake.md --tasks --out website-workspace.tasks.json --force
+design-ai site --from-intake company-website-intake.md --bundle --tasks --out website-handoff-bundle --strict --force
+```
+
+If no intake file is available, use direct fields:
+
+```bash
+design-ai site --init \
+  --name "<site name>" \
+  --live-url <live-url> \
+  --local-path <absolute-target-repo-path> \
+  --page / \
+  --page <priority-page-2> \
+  --flow "<primary user flow>" \
+  --next-actions \
+  --out website-next-actions.md \
+  --force
+```
+
+```bash
+design-ai site --init \
+  --name "<site name>" \
+  --live-url <live-url> \
+  --local-path <absolute-target-repo-path> \
+  --page / \
+  --page <priority-page-2> \
+  --flow "<primary user flow>" \
+  --bundle \
+  --out website-handoff-bundle \
+  --strict \
+  --force
+```
+
+```bash
+design-ai site website-handoff-bundle --bundle-check --strict --json --out website-bundle-check.json --force
+design-ai site website-handoff-bundle --bundle-handoff --strict --out target-repo-handoff.md --force
+```
+
+## Target Repo Verification Plan
+
+Fill this before implementation so the target-repo agent has a clear quality gate.
+
+| Gate | Command or manual check | Required for pilot |
+|---|---|---:|
+| Install | | yes |
+| Lint | | yes |
+| Typecheck | | if available |
+| Unit tests | | if available |
+| Build | | yes |
+| Browser smoke | | yes |
+| Accessibility spot check | | yes |
+| Deployment preview | | if available |
+
+## Stop Conditions
+
+Stop before target-repo edits when any answer is unclear:
+
+- Which repo and branch should be modified?
+- Which single task should be implemented first?
+- Which verification commands must pass?
+- Which credentials or production systems are off limits?
+- Where should implementation evidence be recorded after the target-repo pass?