sppurt 0.0.0-stage → 0.6.0

package/dist/skills/product-parse/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: sppt-product-parse
+description: |
+  주문의 SourceOffering을 안전하게 해석해 기존 ProductOption 매핑을 제안·적용하고,
+  product master와 product mapping 후속 작업까지 연결하는 워크플로우.
+  Use when asked to "상품명 분석", "SKU별 정리", "미매핑 상품 확인", "매핑 설정".
+---
+
+# product-parse
+
+상품 업무는 다음 세 영역으로 나눠 처리합니다.
+
+| 업무 | 책임 | 대표 명령 |
+| --- | --- | --- |
+| `product parse` | intake·후보·기존 옵션 매핑 | `sppt product parse` |
+| `product master` | 마스터 상품·옵션·분류 관리 | `sppt product master ...` |
+| `product mapping` | 미매핑·연결·이력·정책 관리 | `sppt product mapping ...` |
+
+`parse`는 마스터 CRUD나 매핑 이력 관리 명령이 아닙니다. 새 마스터나 분류를 만들어야
+하거나 옵션 BOM을 보완해야 하는 경우에는 자동 확정하지 않고 검토 대기 상태로 남긴 뒤,
+`product master`에서 확정하고 `product mapping`에서 연결합니다.
+
+## 시작 전 확인
+
+- 주문이 임포트되어 있거나 채널 API 동기화가 완료되어 있어야 합니다.
+- 클라우드 인증을 확인합니다.
+
+```bash
+sppt auth whoami
+```
+
+- 처리할 채널·계정·상태·cursor/watermark 범위를 분명히 합니다. 범위가 불명확하면 전체를
+  재처리하지 말고 먼저 대상 건수와 scope를 확인합니다.
+
+## 1. product parse: 자동 intake
+
+### 명령
+
+```bash
+# 기본 동작은 preview run입니다. 마스터·판매채널 매핑은 변경하지 않지만
+# 실행 기록·snapshot·후보·검토 상태는 저장합니다.
+sppt product parse
+sppt product parse --dry-run
+
+# 권장 순서: preview 결과를 확인한 뒤 같은 run을 명시해 적용합니다.
+sppt product parse status <runId>
+sppt product parse --apply --confirm --run-id <runId>
+
+# 새 run 생성부터 적용까지 한 번에 수행하는 사전 승인된 자동 실행
+sppt product parse --apply --confirm
+
+# 실행 결과·pending 항목·적용/충돌 상태 확인
+sppt product parse status <runId>
+```
+
+### 처리 순서
+
+1. 지정한 source/channel account와 state 범위의 SourceOffering을 읽습니다. 기본 state는
+   `unprocessed`이며, 미매핑만 처리하려면 `--state unmapped`를 지정합니다.
+2. `product mapping rules publish`로 활성화된 compiled `product_rules` bundle을 source,
+   policy, master snapshot과 함께 고정합니다.
+3. 상품명·옵션명·raw SKU를 정규화해 기존 마스터 옵션 후보를 찾습니다.
+4. raw SKU 또는 명시 정책으로 하나의 active ProductOption이 확정되고 유효한 SKU/BOM,
+   revision 조건을 만족하는 경우에만 자동 적용 대상으로 삼습니다.
+5. 모호한 identity, SKU 부족, BOM 미완성, 분류 충돌은 `product mapping unmapped`의
+   durable review case로 남깁니다.
+6. 현재 매핑과 같은 대상이면 `unchanged`로 기록하고 매핑을 다시 쓰지 않습니다. 다른
+   대상이 더 강하게 검출되면 `mapping_change` 후보로 만들지만 preview 단계에서는 변경하지
+   않습니다.
+7. 최종 적용이 승인된 매핑 변경은 서버가 하나의 `changeSetId`로 묶어 이력에 기록합니다.
+
+기본 parse와 `--dry-run`은 마스터 상품·옵션·분류와 판매채널 매핑을 변경하지 않습니다. 대신
+run, input manifest, 후보, action plan, review case와 SourceOffering의 parse 상태를 저장할 수
+있습니다. `--apply --confirm` 없이는 매핑을 적용하지 않습니다. 최종 매핑 전에 확인을 받으려면
+반드시 `parse → status → parse --apply --confirm --run-id` 순서를 사용합니다. `--run-id`를
+지정하면 해당 run의 input manifest hash, policy hash, source mapping revision을 다시 검증하고
+snapshot이나 revision이 달라지면 중단합니다. `--run-id`를 생략한 `--apply --confirm`은 새 run을
+만들고 결과를 기다린 뒤 같은 명령 안에서 적용하므로, 별도 review가 끝난 뒤 적용해야 하는 경우에는
+사용하지 않습니다.
+
+신규 마스터 상품·ProductOption·classification node 생성, 마스터 field 수정, BOM 구성
+변경은 parse가 자동 적용하지 않습니다. 이 결과는 pending review로 남기고 다음 순서로
+처리합니다.
+
+```bash
+sppt product master create --name "알텐바흐 316Ti 멀티쿠커"
+sppt product master option create <productId> \
+  --name "20cm" --option-type variant --sku-id <skuId>
+sppt product master classification create --kind category --name "냄비"
+sppt product mapping map <sourceOfferingId> --product-option-id <masterOptionId>
+```
+
+`status`는 run 상태와 pending 사유를 확인하는 읽기 전용 명령입니다. parse 결과를 임의의
+후보 선택으로 확정하지 말고, 신규 master·classification·BOM이 필요한지 먼저 판단합니다.
+
+### 이미 매핑된 항목의 처리
+
+- 현재 매핑 대상과 parse 후보가 같으면 `unchanged`로 처리합니다. 기존 decision과 매핑을
+  덮어쓰지 않습니다.
+- 현재 매핑과 다른 대상이 더 강하게 검출되면 `mapping_change`로 표시합니다. preview에서는
+  기존 매핑을 유지하며, `status`에서 대상과 근거를 확인한 뒤 `--apply --confirm --run-id`로
+  명시적으로 승인해야 합니다.
+- 적용 조건은 신규 매핑과 동일하게 canonical identity, 동일한 mapping revision, active
+  ProductOption, 실행 가능한 SKU/BOM입니다. 조건이 맞지 않거나 판단이 모호하면 기존 매핑을
+  유지하고 conflict 또는 review case로 남깁니다.
+- 재매핑이 적용되면 기존 decision을 삭제하지 않고 supersedes 관계의 새 decision과 새
+  `changeSetId`를 기록합니다. 잘못된 재매핑은 `product mapping rollback`으로 되돌립니다.
+
+## 2. product master: 확정 데이터 관리
+
+마스터 상품과 옵션은 이 영역에서 명시적으로 생성·수정합니다. 생성·수정에는 optimistic
+revision과 idempotency를 사용합니다. 옵션 create/update CLI는 현재 product revision과 옵션
+revision을 서버에서 읽어 내부적으로 configuration preview를 만든 뒤 즉시 적용합니다. 별도
+review 후 confirm하는 최종 매핑 명령과는 다른 동작입니다.
+
+```bash
+sppt product master list --query "멀티쿠커"
+sppt product master create --name "알텐바흐 316Ti 멀티쿠커" --category-id <categoryId>
+sppt product master update <productId> --revision <n> --name "알텐바흐 316Ti 멀티쿠커 2.0"
+
+sppt product master option list <productId>
+sppt product master option create <productId> \
+  --name "20cm" --option-type variant --sku-id <skuId>
+sppt product master option update <productId> <optionId> \
+  --name "20cm 본품"
+```
+
+### 분류 관리
+
+분류는 별도 최상위 업무가 아니라 `product master` 아래에서 관리합니다. 지원 kind는
+`brand`, `category`, `productLine`입니다.
+
+```bash
+sppt product master classification list --kind category
+sppt product master classification create --kind category --name "냄비"
+sppt product master classification update --kind category <id> --revision <n> \
+  --name "냄비·웍"
+sppt product master classification archive --kind category <id> --revision <n>
+sppt product master classification restore --kind category <id> --revision <n>
+```
+
+상품 분류 연결이 빠져 있으면 매핑과 별개로 분류 연결 필요 review issue로 남깁니다. parse는
+분류 후보만 pending으로 제안하며, 분류 디렉터리와 상품 연결은 master에서 확정합니다.
+
+### 옵션과 BOM
+
+단품은 direct SKU를 사용하고, 세트·프로모션은 옵션의 BOM 구성으로 관리합니다. 구성 변경은
+현재 active 옵션을 보존한 전체 configuration preview를 확인한 뒤 적용합니다. parse가
+BOM을 추측하거나 불완전한 BOM을 자동 확정하게 두지 않습니다.
+
+## 3. product mapping: 연결·이력·정책
+
+### 미매핑과 직접 연결
+
+```bash
+sppt product mapping unmapped
+
+# 첫 호출은 preview만 반환하며 변경하지 않습니다.
+sppt product mapping map <sourceOfferingId> --product-option-id <masterOptionId>
+
+# preview 결과와 대상 revision을 확인한 뒤 같은 요청에 confirm을 붙입니다.
+sppt product mapping map <sourceOfferingId> \
+  --product-option-id <masterOptionId> --confirm
+
+# 해제도 동일하게 preview 후 confirm합니다.
+sppt product mapping unmap <sourceOfferingId>
+sppt product mapping unmap <sourceOfferingId> --confirm
+```
+
+map/unmap은 단건이어도 preview token과 대상 mapping revision을 검증합니다. `--confirm` 없는
+호출은 preview만 반환하고 변경하지 않으며, 확인 시점에 source가 바뀌었거나 preview binding이
+없으면 다시 preview를 만들고 중단합니다. 대상 ProductOption이 없으면 먼저 `product master`에서
+생성·확정합니다.
+
+### history와 rollback
+
+```bash
+sppt product mapping history --from "2026-09-02 10:00" --to "2026-09-02 10:10"
+
+# changeSetId를 명시하는 경우에도 먼저 영향 범위를 확인합니다.
+sppt product mapping rollback --changeset <changeSetId>
+sppt product mapping rollback --changeset <changeSetId> --confirm
+
+# timestamp는 history에서 대상을 고르는 편의 selector입니다.
+sppt product mapping rollback --at "2026-09-02 10:05"
+sppt product mapping rollback --at "2026-09-02 10:05" --confirm
+```
+
+사람이 새 `changeSetId`를 만들거나 배정하지 않습니다. rollback에서는 서버가 만든 기존 ID를
+선택할 수 있지만, map, unmap, parse 자동 적용, rollback 실행 자체의 `changeSetId`는 서버가
+자동 생성합니다. `--at`은 해당
+시점의 history를 찾는 selector일 뿐이며, 실제 rollback 단위는 서버가 선택한 구체적인
+change set입니다. 시간만으로 대상이 모호하거나 현재 revision이 달라지면 자동 rollback하지
+않고 preview 또는 conflict를 반환합니다. rollback은 기존 이력을 삭제하지 않고 보정 decision과
+새 change set을 추가합니다.
+
+### product_rules 정책 authoring
+
+`product_rules`는 사람이 작성·검토하는 Markdown authoring policy입니다. 아래 lifecycle로만
+관리하고, parse는 publish된 정책 bundle을 snapshot에 고정해 사용합니다.
+
+```bash
+sppt product mapping rules show
+sppt product mapping rules set ./product-rules.md
+sppt product mapping rules publish
+```
+
+- `show`로 현재 draft와 active 정책을 확인합니다.
+- `set`은 Markdown 원문을 draft로 저장합니다.
+- `publish`는 compile·검증에 성공한 draft만 active 정책으로 교체합니다.
+- 작성 가능한 규칙은 normalization/noise, alias, explicit SKU/source mapping, option·quantity
+  pattern, classification suggestion 중심으로 제한합니다.
+- 자유로운 설명은 검토 참고용 context로 보존할 수 있지만 canonical mapping을 단독으로
+  결정하지 않습니다.
+- 정책을 publish해도 기존 매핑을 자동 재작성하지 않습니다. 새 parse 실행과 별도 적용이
+  필요합니다.
+
+`set`의 Markdown은 정책 원문을 제출하는 입력이며 상품 마스터나 매핑 데이터를 직접 가져오는
+임포트 경로가 아닙니다. 정책이 없거나 compile되지 않으면 이름 유사도만으로 확정하지 말고
+`policy_not_applied` 또는 pending으로 남깁니다.
+
+## 안전 원칙
+
+1. parse는 항상 dry-run으로 시작하고, 실제 변경은 `--apply --confirm`을 함께 지정합니다.
+2. map/unmap은 preview 결과·대상·현재 revision을 확인한 뒤 `--confirm`합니다.
+3. raw SKU, canonical identity, 명시 정책으로 대상이 하나로 확정되지 않으면 선택하지 않습니다.
+4. 신규 master, classification, option, BOM 변경은 pending review로 남기고 master에서 먼저
+   확정합니다.
+5. input manifest hash, policy hash, source mapping revision이 확인 시점과 다르면 재실행하거나
+   충돌로 보고합니다.
+6. 자동화가 생성한 `changeSetId`와 history를 보존하고, 기존 decision을 덮어쓰지 않습니다.
+7. 적용 후 `sppt product parse status <runId>`와 `sppt product mapping unmapped`로 pending,
+   conflict, projection 상태를 다시 확인합니다.

package/dist/skills/product-parse/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "상품명 파싱"
+  short_description: "상품명 → SKU/카테고리/제품라인 해체"
+  brand_color: "#2563EB"
+  default_prompt: "$sppt-product-parse 상품명 파싱해줘"
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/product-sync/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: sppt-product-sync
+description: |
+  소싱 상품을 판매 채널에 배치로 동기화/등록하는 워크플로우.
+  Use when asked to "상품 동기화", "배치 등록", "전채널 등록", "상품 복사".
+---
+
+# product-sync
+
+소싱 상품을 여러 판매 채널에 배치로 등록/동기화하는 워크플로우.
+
+## When to use
+
+- "상품 전채널에 올려줘", "배치로 등록해줘", "카페24 상품 쿠팡에도 올려줘"
+- 한 채널에 등록된 상품을 다른 채널로 복사할 때
+- 다수 상품을 한번에 등록할 때
+
+## Prerequisites
+
+- 최소 2개 판매 채널 설정 완료
+- 등록할 상품 데이터 (JSON 파일 또는 기존 채널 상품 ID)
+
+## Steps
+
+### 1. 원본 상품 확인
+
+기존 채널에서 상품 목록을 확인합니다:
+
+```bash
+sppt product list cafe24
+```
+
+또는 특정 상품 상세:
+
+```bash
+sppt product get cafe24 <productId>
+```
+
+### 2. 배치 동기화 실행
+
+한 채널의 상품을 다른 채널로 배치 복사:
+
+```bash
+sppt product sync-batch --from cafe24 --to coupang --ids <id1,id2,id3>
+```
+
+전체 채널 동시 등록:
+
+```bash
+sppt product register --all-channels --file /tmp/product.json
+```
+
+### 3. 결과 확인
+
+배치 결과가 CSV로 저장됩니다. 실패한 항목을 확인합니다:
+
+```bash
+# 결과 CSV에서 실패 건 확인
+```
+
+실패한 상품은 에러 메시지를 확인하고 개별 재시도합니다:
+
+```bash
+sppt product register coupang --file /tmp/failed-product.json
+```
+
+### 4. 매핑 등록
+
+채널 간 상품 매핑을 등록하여 재고 동기화에 활용합니다:
+
+```bash
+sppt mapping add <cafe24Id> <coupangId>
+```
+
+## Error handling
+
+- **카테고리 코드 불일치**: 채널별 카테고리 체계가 달라 매핑 필요
+- **이미지 URL 차단**: 일부 채널은 외부 이미지 URL을 차단 — 이미지 업로드 필요
+- **필수 필드 누락**: 채널별 필수 입력 항목이 다름 (쿠팡: 카테고리 코드 필수)
+
+## Notes
+
+- `--all-channels`는 설정된 모든 판매 채널에 동시 등록합니다
+- 배치 복사 결과는 자동으로 CSV에 기록됩니다
+- 채널 간 가격 차등은 `--markup` 옵션으로 조정 가능합니다

package/dist/skills/product-sync/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "상품 배치 동기화"
+  short_description: "소싱→판매 채널 배치 상품 동기화"
+  brand_color: "#2563EB"
+  default_prompt: "$sppt-product-sync 상품 동기화해줘"
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/settlement-deposit/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: sppt-settlement-deposit
+description: |
+  통장 입금 내역 CSV를 임포트해서 정산 대사를 완성하는 워크플로우.
+  Use when asked to "입금 내역 넣어줘", "통장 CSV 임포트", "실입금 확인", "정산 대사".
+---
+
+# settlement-deposit
+
+은행 CSV 파일을 DB에 올려서 입금 예정액 vs 실입금을 자동 대조하는 워크플로우.
+
+## When to use
+
+- "통장 입금 내역 넣어줘", "은행 CSV 임포트해줘"
+- "실입금이랑 정산 예정액 비교하고 싶어"
+- 대시보드 정산 페이지에서 실입금 컬럼이 비어있을 때
+
+## Prerequisites
+
+- 주문 동기화 완료 (`/sppt-order-collect` 먼저 실행)
+- 은행 CSV 파일 준비 (KB·신한·우리·하나 자동 감지)
+
+## Steps
+
+### 1. 파일 확인
+
+사용자에게 CSV 파일 경로를 물어봅니다:
+
+> 입금 내역 CSV 파일 경로를 알려주세요. (예: ~/Downloads/kb_2026_05.csv)
+
+파일 경로를 받으면 진행합니다.
+
+### 2. 미리보기 (dry-run)
+
+실제 임포트 전에 어떤 데이터가 들어오는지 확인합니다:
+
+```bash
+sppt settlement deposit <file> --dry-run
+```
+
+미리보기 결과를 사용자에게 보여주고 확인을 받습니다:
+
+> N건의 입금 내역이 감지됐습니다. 임포트할까요?
+
+### 3. 날짜 범위 필터 (선택)
+
+사용자가 특정 기간만 넣고 싶다면:
+
+```bash
+sppt settlement deposit <file> --from 2026-05-01 --to 2026-06-01 --dry-run
+```
+
+범위 필터 없이 전체를 넣어도 됩니다.
+
+### 4. 임포트 실행
+
+확인 후 실제로 저장합니다:
+
+```bash
+sppt settlement deposit <file>
+```
+
+### 5. 결과 안내
+
+임포트 완료 후:
+
+> N건의 입금 내역을 저장했습니다.
+> 대시보드 정산 페이지 → 카페24 → '정산 대사' 패널에서 실입금과 오차를 확인하세요.
+
+### 6. 잘못 넣은 항목 삭제 (선택)
+
+실수로 넣은 항목이 있으면:
+
+```bash
+sppt settlement deposit delete --date 2026-05-06 --provider 카페24페이먼
+```
+
+## Error handling
+
+- **파일 형식 미지원**: 지원 은행(KB·신한·우리·하나) 확인 후 재시도 안내
+- **중복 데이터**: CLI가 자동으로 중복 체크하므로 걱정 불필요
+- **날짜 파싱 오류**: `--from`/`--to` 형식 `YYYY-MM-DD` 확인
+
+## Notes
+
+- 같은 파일을 다시 올려도 중복 저장 안 됨
+- 임포트 후 대시보드를 새로고침하면 실입금·오차 컬럼이 채워짐
+- 매월 말 정산 마감 후 CSV를 받아서 넣는 루틴으로 활용하면 효과적

package/dist/skills/settlement-report/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: sppt-settlement-report
+description: |
+  멀티채널 정산 현황 조회 + 수수료 계산 + 수익 요약 워크플로우.
+  Use when asked to "정산 확인", "이번 달 수익", "수수료 얼마야", "실수령액".
+---
+
+# settlement-report
+
+멀티채널 정산 현황을 조회하고 수수료/실수령액을 계산하는 워크플로우.
+
+## When to use
+
+- "이번 달 정산 확인해줘", "수수료 얼마나 나가?", "실수령액 계산해줘"
+- 채널별 정산 비교가 필요할 때
+- 수수료 규칙을 설정/변경할 때
+
+## Prerequisites
+
+- 최소 1개 판매 채널 설정 완료
+- 수수료 규칙 설정 권장: `sppt settlement fee list`
+
+## Steps
+
+### 1. 수수료 규칙 확인
+
+```bash
+sppt settlement fee list
+```
+
+채널별 수수료 규칙이 설정되어 있는지 확인합니다.
+없으면 사용자에게 수수료율을 물어보고 설정합니다:
+
+```bash
+sppt settlement fee set coupang --rate 10.8
+sppt settlement fee set cafe24 --rate 3.3
+sppt settlement fee set smartstore --rate 5.5
+```
+
+### 2. 정산 요약 조회
+
+```bash
+sppt settlement summary --days 30
+```
+
+채널별 정산 합계를 조회합니다. 특정 채널만 보려면:
+
+```bash
+sppt settlement summary coupang --days 30
+```
+
+### 3. 정산 목록 상세
+
+```bash
+sppt settlement list --days 30
+```
+
+건별 정산 내역을 확인합니다.
+
+### 4. 개별 주문 정산 계산
+
+특정 주문의 수수료/실수령액을 계산합니다:
+
+```bash
+sppt settlement calc coupang <orderId> --amount 29900
+```
+
+출력 예시:
+```
+정산 계산: coupang 주문 #12345
+──────────────────────────
+판매가:       29,900원
+수수료 (10.8%): -3,229원
+배송비:       -3,000원
+──────────────────────────
+실수령액:     23,671원
+마진율:       20.8%
+```
+
+### 5. 결과 요약
+
+사용자에게 채널별 정산 비교표를 제공합니다:
+
+```
+📊 정산 요약 (최근 30일)
+────────────────────────────────────────
+채널          매출      수수료     실수령    마진율
+cafe24       850,000   28,050    821,950   96.7%
+coupang    2,150,000  232,200  1,917,800   89.2%
+smartstore   620,000   34,100    585,900   94.5%
+────────────────────────────────────────
+합계       3,620,000  294,350  3,325,650   91.9%
+```
+
+### 6. 은행 입금 내역 임포트 (카페24 대사용)
+
+카페24 정산 대사를 위해 실제 통장 입금 내역을 DB에 올립니다:
+
+```bash
+# KB·신한·우리·하나 CSV 자동 감지
+sppt settlement deposit <file.csv>
+
+# 날짜 범위 필터 + 미리보기
+sppt settlement deposit <file.csv> --from 2026-04-01 --to 2026-05-01 --dry-run
+
+# 잘못 올린 항목 삭제
+sppt settlement deposit delete --date 2026-04-06 --provider 카페24페이먼
+```
+
+임포트 후 대시보드 정산 페이지 → 카페24 → '정산 대사' 패널에서 확인합니다.
+
+## Error handling
+
+- **수수료 규칙 미설정**: 채널 기본 수수료율로 안내 후 설정 유도
+- **정산 데이터 없음**: 조회 기간 확대 또는 주문 데이터 임포트 안내
+
+## Notes
+
+- 수수료율은 채널·카테고리·판매자 등급에 따라 다를 수 있음
+- 정산 이력은 대시보드에서 확인할 수 있습니다
+- 매월 정산 리포트로 채널별 수익성 비교 권장

package/dist/skills/settlement-report/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "정산 현황 리포트"
+  short_description: "멀티채널 정산 조회 + 수수료 계산 + 수익 요약"
+  brand_color: "#2563EB"
+  default_prompt: "$sppt-settlement-report 정산 현황 보여줘"
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/shopport/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: shopport
+description: |
+  Legacy /shopport alias for Sppurt CLI help and skill discovery. /sppt remains canonical.
+  Use when asked about "shopport", "Sppurt help", or available skills.
+---
+
+# Sppurt (legacy /shopport alias)
+
+> `/sppt` 스킬과 동일합니다. Sppurt CLI 도움말 + 스킬 목록을 보려면 아래를 실행하세요.
+
+먼저 CLI 도움말을 확인합니다:
+
+```bash
+sppt --help
+```
+
+## 에이전트 인증
+
+브라우저를 열 수 없는 에이전트는 발급받은 원문 토큰을 표준 입력으로 등록한다.
+
+```bash
+printf %s "$SHOPPORT_AGENT_TOKEN" | sppt auth token set --stdin
+sppt auth whoami
+```
+
+`sppt auth token remove`는 이 기기의 등록값만 지우며 서버 토큰을 폐기하지 않는다.
+
+## 사용 가능한 스킬
+
+| 스킬 | 설명 |
+|---|---|
+| `/sppt` | Sppurt 전체 도움말 + 스킬 목록 |
+| `/sppt-daily-report` | 매일 아침 매출/주문 브리핑 |
+| `/sppt-order-collect` | 멀티채널 주문 한번에 모아보기 |
+| `/sppt-order-fulfill` | 주문 확인 → 소싱 발주 → 송장 등록 |
+| `/sppt-source-to-register` | 소싱 검색 → 마진 계산 → 판매 채널 등록 |
+| `/sppt-waterfall-source` | 3개 소싱채널 워터폴 가격 비교 |
+| `/sppt-product-sync` | 소싱→판매 배치 상품 동기화 |
+| `/sppt-product-parse` | 상품명 → SKU/카테고리/제품라인 해체 |
+| `/sppt-inventory-sync` | 멀티채널 재고 분배 + 동기화 |
+| `/sppt-price-monitor` | 소싱가 변동 감지 → 마진 체크 → 판매가 조정 |
+| `/sppt-weekly-analysis` | 전주 대비 매출 변화 원인 분석 + 채널 수수료 최적화 |
+| `/sppt-settlement-report` | 정산 현황 조회 + 수익 요약 |
+| `/sppt-settlement-deposit` | 통장 입금 CSV 임포트 → 정산 대사 |
+| `/sppt-policy-ask` | PG사·판매채널 수수료·정산 정책 Q&A |
+| `/sppt-cost-calc` | 원가/마진/수수료 계산 |
+| `/sppt-cost-register` | SKU 원가 등록·관리 |
+| `/sppt-trend-research` | 트렌드 키워드 리서치 |
+| `/sppt-dashboard` | 운영 대시보드 띄우기 |
+| `/sppt-status-check` | 전채널 연결 + 건강 체크 |
+| `/sppt-update` | CLI 버전 업데이트 + 릴리즈 노트 확인 |
+
+## Quick Start
+
+```bash
+sppt init              # 채널 온보딩
+sppt status            # 연결 상태 확인
+sppt context           # AI용 스토어 브리핑
+sppt order list cafe24 # 주문 조회
+sppt order exclude <id> --reason "테스트"  # 매출 집계에서 제외
+sppt order exclude --ids id1,id2 --inventory-deduction  # 집계 제외 + 재고 차감 유지
+sppt order excluded    # 제외된 주문 목록
+sppt report --by category --explain  # 수량 기여 분해
+sppt analytics cafe24 visitors --period 7d # 카페24 방문자수 조회
+sppt analytics cafe24 visitpaths --type domains --period 7d # 카페24 유입경로 조회
+sppt product mapping unmapped        # durable 미매핑 검토 큐 조회
+sppt crm cafe24 groups                # cafe24 회원등급 조회
+sppt crm cafe24 customers --limit 30  # cafe24 회원목록 조회
+sppt coupon list cafe24 --name "재구매" # 카페24 쿠폰 목록 + 다운로드 URL
+sppt coupon issues cafe24 <coupon_no> # 쿠폰 발급내역 조회
+sppt coupon revoke cafe24 <member_id> <coupon_no> --confirm # 회원 쿠폰 회수
+sppt coupon link cafe24 <coupon_no> --domain birthtii.com # 쿠폰 다운로드 URL 조립
+sppt settlement deposit <file.csv>   # 은행 입금 내역 CSV 임포트 (KB·신한·우리·하나)
+sppt settlement deposit delete --date YYYY-MM-DD --provider <입금처>  # 입금 내역 삭제
+```
+
+## 쿠폰
+
+```bash
+sppt coupon list cafe24 [--name <검색어>] [--json]
+sppt coupon get cafe24 <coupon_no> [--json]
+sppt coupon issues cafe24 <coupon_no> [--member <member_id>] [--order-status <status>] [--json]
+sppt coupon revoke cafe24 <member_id> <coupon_no> [--confirm]
+sppt coupon link cafe24 <coupon_no[,coupon_no...]> [--domain <domain>] [--copy]
+sppt coupon create <channel> --name <name> --type <type> --value <N>
+sppt coupon issue <channel> <couponId> --members <id1,id2,...>
+sppt coupon support
+```
+
+## CRM
+
+```bash
+sppt crm cafe24 groups [--json]
+sppt crm cafe24 customers [--limit N] [--group-no <no>] [--json]
+sppt crm cafe24 customer <member_id> [--json]
+sppt crm cafe24 group assign <member_id> --group-no <no> [--fixed] [--dry-run]
+sppt crm balance
+sppt crm sms send --content "본문" --to <phone>
+```
+
+## 분석/리포트
+
+```bash
+sppt analytics cafe24 visitors [--period 7d] [--device total] [--format day] [--json]
+sppt analytics cafe24 visitpaths [--type domains|ads|keywords] [--period 7d] [--json]
+```
+
+판매 채널: cafe24, coupang, smartstore, shopify, toss-shopping, 29cm, musinsa
+소싱 채널: domemae, domeggook, specialoffer, cjdropshipping, 1688
+물류 채널: dada-erp, ezadmin, onewms, sabangnet, boxhero, ecount-erp, douzone-wehago, playauto, argo, poomgo
+
+### 광고·프로모션 운영
+
+`sppt ads meta --help`로 계정·성과·손익·규칙·판단·승인·실행·감사 기록을 조회/조정한다.
+전체 기록은 `--all --json`, 특정 계정은 `--account <id>`를 사용한다. 기록 날짜는 UTC다.
+규칙 변경은 조회 revision으로 저장→미리보기→게시→버전 적용 순서이며 자동 승인과 별개다.
+승인·실행에는 검토한 `--plan-hash`를 명시한다. 관리자/실행 scope/서버 grant/한도를
+우회하지 않으며 timeout 후에는 실행 기록 조회와 reconcile을 사용하고 실행을 재전송하지 않는다.
+수동 Meta sync는 수집·판단만 수행하며 광고 변경 실행은 별도 명령이다.
+`sppt promotions --help`는 행사 조회·생성·수정·미리보기·게시·취소·보관·투영작업 조회를 제공한다.
+변경은 멱등키, 수정은 revision, 게시는 previewToken을 사용한다. `sppt ads competitors --help`는
+경쟁사 광고/추적 설정이다. 최소권한 scope는 `ads:read/write/execute`, `promotions:read/write`다.