@wonseok-han/confluence-sync 1.7.0 → 2.0.0

package/docs/user/CLI.md

@@ -0,0 +1,366 @@
+# CLI 사용 안내
+
+[← README로 돌아가기](../../README.md)
+
+명령별 동작과 옵션, 변경 확인·문서 선택·업로드·가져오기·복구를 설명합니다.
+
+- [CLI에서 작업하기](#cli에서-작업하기)
+- [업로드 문서 선택 (Add)](#업로드-문서-선택-add)
+- [원격 변경 확인 (Fetch)](#원격-변경-확인-fetch)
+- [변경된 문서만 Pull](#변경된-문서만-pull)
+- [로컬 문서 복구와 수정 원복](#로컬-문서-복구와-수정-원복)
+- [파일 이동과 자동 매핑](#파일-이동과-자동-매핑)
+- [Push — Markdown → Confluence](#push--markdown--confluence)
+- [폴더 = 페이지 계층](#폴더--페이지-계층)
+- [변환 규칙](#변환-규칙)
+- [표 너비 지정](#표-너비-지정)
+- [다른 동기화 폴더의 문서 링크](#다른-동기화-폴더의-문서-링크)
+- [섹션 링크 (앵커)](#섹션-링크-앵커)
+- [변경 감지와 매핑](#변경-감지와-매핑)
+- [동기화 제외 (로컬 전용 문서 유지)](#동기화-제외-로컬-전용-문서-유지)
+- [v1의 --rebuild 이전 안내](#v1의---rebuild-이전-안내)
+- [Pull — Confluence → Markdown](#pull--confluence--markdown)
+- [매핑 기록](#매핑-기록)
+
+## CLI에서 작업하기
+
+`csync`는 도움말만 표시합니다. `csync <명령> --help`로 해당 명령의 옵션과 예제를 확인할 수 있습니다.
+
+```bash
+csync init                  # .env 생성 후 값 입력
+csync pull                  # 받을 원격 문서 가져오기
+csync fetch                 # 원격 메타데이터 조회(2분 캐시)
+csync status                # 받을 변경·보낼 변경·양쪽 변경·확인 필요
+csync pull                  # 원격에서만 바뀐 문서 가져오기
+# 로컬 문서 편집
+csync diff 문서.md
+csync add 문서.md
+csync push --dry-run --verify
+csync push
+```
+
+`status`는 로컬 문서와 **저장된 마지막 Fetch 결과**를 함께 보여주며 API를 호출하거나 문서·매핑·선택을 저장하지 않습니다. 원격 조회 시각을 표시하고 조회 전에는 **원격 미확인**, 2분이 지나면 **이전 조회 결과**로 안내합니다. 현재 원격 확인은 `fetch`로 실행하세요. `받을 변경`은 Pull 대상, `양쪽 변경`은 비교 대상이며 재추가 필요·파일 누락·원격 조회 불가·기준 버전 미확인은 `확인 필요`로 구분합니다. `[추가됨]`·`[미선택]`은 업로드 선택 상태이며 원격 충돌 검사를 대신하지 않습니다. 로컬 삭제를 원격 삭제로 처리하지 않습니다.
+
+터미널에서는 받을 변경을 청록색, 보낼 변경을 파란색, 업로드에 추가한 문서를 초록색, 양쪽 변경·오류를 빨간색, 재확인 항목을 노란색으로 표시합니다. `diff`의 삭제 줄은 빨강, 추가 줄은 초록입니다. 문구와 기호도 유지하므로 색 없이 구분할 수 있습니다. 파이프·리다이렉트에서는 기본적으로 색을 제거하며 `--no-color` 또는 `NO_COLOR=1`로 끌 수 있습니다. `FORCE_COLOR=1`은 강제 활성, `FORCE_COLOR=0`은 비활성이고 명시적인 색상 끄기가 우선합니다.
+
+CLI 작업 중에는 시간 표시 없이 터미널 한 줄에 **로딩 표시·현재 단계**를 보여줍니다. 스피너는 별도 스레드에서 출력해 동기 파일 검사·Markdown 계산 중에도 움직이며, 완료·오류·중단 시 표시용 스레드를 정리합니다. Push의 전처리·원격 검증·문서 처리, Pull의 다운로드·기준 계산, Fetch의 조회 구간을 구분합니다. 전체 크기를 모르는 다운로드에는 진행률을 추정해 붙이지 않습니다. 로그는 그대로 남기고 완료·실패·중단 결과를 표시합니다. 파이프·리다이렉트·CI·단순 터미널에서는 회전 문자와 줄 덮어쓰기 대신 시작·종료 안내만 **stderr**에 남겨 stdout의 상태·diff 내용을 유지합니다. 도움말·버전·대화형 .env 입력과 웹 서버 대기에는 로딩을 표시하지 않습니다.
+
+CLI의 `push --dry-run`은 권장 절차이며 필수 승인은 아닙니다. 실제 Push에서는 미리보기 여부와 관계없이 원격 버전 충돌을 검사합니다. 웹에서는 미리보기가 필수입니다. `add`는 파일 내용을 복사하지 않으므로 선택 후 수정했다면 다시 추가해야 합니다. `push 문서.md`는 저장된 선택과 별개로 지정한 파일을 바로 처리합니다.
+
+기존 로컬 문서부터 시작한다면 `.env` 준비 후 `csync init --connect`로 연결하고 문서를 추가하세요. `csync init --base <기존 폴더>`는 그 폴더에 `.env`를 생성합니다. `.env` 생성·연결·메타데이터 이전의 차이는 `csync init --help`에서 확인할 수 있습니다.
+
+## 업로드 문서 선택 (Add)
+
+기준 폴더 전체가 작업공간입니다. 기본 Push는 **직접 추가한 문서만** 처리합니다.
+
+```bash
+csync status                 # 로컬·마지막 원격 조회·업로드 선택 확인 (API 호출 없음)
+csync diff 문서.md            # 마지막 성공 기준본과 로컬 Markdown 비교
+csync diff 문서.md --remote   # 해당 원격 페이지 본문만 1회 조회해 비교
+csync add 문서.md 폴더        # 다음 업로드에 포함할 문서 선택
+csync push --dry-run         # 추가한 문서의 업로드 계획 확인
+csync push                   # 추가한 문서만 업로드
+csync unstage 문서.md         # 선택 해제 (원본 문서 유지)
+csync unstage .              # 모든 선택 해제
+```
+
+선택은 `.csync/index.json`에 저장합니다. 대상이 비어 있으면 Push는 중단합니다. `add .`은 작업공간의 문서를 모두 추가합니다. 추가 후 문서·참조 첨부·변환되는 링크가 바뀌면 다시 `add`해야 합니다. 문서 전체 단위 선택이며, Git처럼 내용을 복제해 두거나 일부 줄만 저장하지는 않습니다.
+
+선택 정보는 Confluence 연결·스페이스·원격 루트를 기준으로 검증하므로 같은 문서 폴더를 CLI·로컬 웹·배포 웹에서 사용할 수 있습니다. 이전 형식의 선택 정보도 보존합니다. 경로 또는 연결이 바뀌어 기존 선택을 검증할 수 없으면 CLI의 `csync add` 또는 웹의 **최신 내용 반영**으로 해당 문서를 다시 확인해야 업로드할 수 있습니다.
+
+성공한 항목과 변경 없는 항목만 선택에서 해제하고, 실패한 항목은 남깁니다. 변경 없는 문서는 기본 Push에서 원격 조회·폴더 준비를 건너뜁니다. 실제 업로드는 기존 원격 버전·스페이스·위치 검증을 계속 수행하며 Fetch 캐시로 충돌 검사를 대체하지 않습니다. `--verify`는 변경 없는 대상도 조회합니다.
+
+로컬 diff 기준본은 이후 Pull·Push 성공 시 `.csync/objects/`에 저장합니다. 과거 본문 없이 해시만 있는 기존 문서는 원래 내용을 복원할 수 없습니다. 웹에서는 **diff 보기**를 누르면 저장된 과거 기준본 유무와 관계없이 해당 원격 페이지 본문을 1회 조회해 현재 로컬 본문과 바로 비교합니다. 원격 연결이 없는 새 문서는 빈 본문과 비교합니다. 로컬 자동 확인·새로고침·Fetch만으로 원격 본문을 읽지는 않습니다. Fetch에 원격 수정으로 표시된 문서의 diff는 현재 원격 본문을 조회해 비교합니다. CLI는 `--remote`를 명시해야 원격을 조회합니다. 이는 현재 원격 HTML의 근사 Markdown 변환과 로컬 본문 비교이고 과거 동기화 기준과의 비교는 아닙니다. 첨부 자체의 바이트 차이는 본문 diff에 표시하지 않습니다.
+
+같은 부모 폴더에서 Markdown 파일명만 바꿔도 frontmatter의 `pageId`와 `title`로 기존 페이지 연결·제목을 유지합니다. 변경 목록에는 **로컬 경로 변경**, 미리보기에는 **로컬 경로 연결**로 표시하며 실제 Push는 로컬 매핑 경로만 갱신합니다. 본문이나 제목도 수정했다면 원격 갱신하고, 실제 부모가 달라졌다면 이동 대상으로 처리합니다.
+
+업로드 미리보기 승인은 문서·첨부·매핑·설정의 파일 내용으로 검증합니다. OneDrive 등의 파일 시각만 바뀌면 승인을 유지하고, 실제 내용이 바뀌면 다시 미리보기해야 합니다. 원격 조회가 없는 `[위치 확인/이동]`은 본문 변경 없이 위치를 확인할 예정이라는 뜻이며, 실제 이동 여부는 Push에서 원격을 조회한 뒤 결정합니다.
+
+웹 작업 중에는 **우하단 진행 카드에 작업명·진행 내역·경과 시간**을 표시하고 실행 버튼에도 로딩 표시를 붙입니다. Fetch·Pull·Push는 요청 응답 후에도 서버 작업과 결과 반영이 끝날 때까지 유지하며, 새로고침 후 진행 중인 작업도 서버 시작 시각으로 복원합니다. 상태 조회가 끊기면 **진행 상태 확인 필요**로 표시하고 기존 상태 재확인 기능을 사용합니다. diff·표 서식·문서 미리보기·변환·연결 설정에도 요청별 로딩을 제공하며 모달 내부에도 표시합니다. 자동 로컬 확인은 버튼과 목록을 잠그지 않고, 350ms 이상 걸릴 때 목록 옆에 작은 표시만 보여줍니다. 추가 API 조회나 화면 전체 재렌더링은 하지 않으며 모션 감소 설정을 따릅니다.
+
+웹의 **.env 연결 설정 → .env 샘플 다운로드**에서 `confluence.env.example`을 받을 수 있습니다. 실제 계정·토큰·경로는 들어 있지 않습니다. 빈 값을 채운 뒤 `.env 가져오기`로 선택하거나 파일명을 `.env`로 바꿔 기준 폴더에 저장하세요.
+
+**대상 및 실행 내역 → 로그 다운로드**는 현재 작업의 로그를 `.log` 파일로 저장합니다. 실행 중·실패한 작업도 현재까지의 로그를 받을 수 있고, 작업 종류·상태·시작/종료 시각을 함께 기록합니다. 서버가 가린 토큰·Basic 인증값은 그대로 가려지며 연결 설정 전체를 내보내지 않습니다. 문서 경로와 오류 메시지는 로그에 포함됩니다. 다운로드는 브라우저에 받은 로그의 사본을 저장하며 별도 Confluence 조회나 작업 재실행은 하지 않습니다.
+
+웹에서는 `.env 연결 설정`이 미리보기처럼 기본적으로 접혀 있고, **Confluence** 패널에서 변경사항과 실행 기능을 함께 제공합니다. 상단에는 작업공간·Fetch/Pull·변경 목록을, 하단에는 선택 문서 미리보기·업로드를 배치합니다. 참조 폴더·원격 검증 옵션은 기본적으로 접힌 **추가 설정**에 있습니다. 문서별 **diff 보기**로 읽기 전용 Monaco 비교 화면을 열 수 있습니다. 선택 추가·해제는 로컬 서버 요청 1회이며 Confluence API를 호출하지 않습니다. 추가는 선택한 문서만 검사하고, 해제는 선택 목록만 저장하며 전체 변환 검사를 반복하지 않습니다. Confluence 화면이 보이고 다른 작업이 없을 때 5초 간격으로 로컬 파일을 확인합니다. 파일·설정 지문이 같으면 기존 분석을 재사용하고, 변경된 경우에만 다시 변환·분석합니다. 자동 확인은 원격 API를 호출하지 않습니다. 수동 Fetch는 기존 배치 메타데이터 조회·캐시·Pull 연동 기능을 유지하면서 같은 목록에 로컬 수정·원격 수정·양쪽 수정 및 조회 불가를 표시합니다. 원격 수정만 있는 문서는 업로드에 새로 포함하지 않습니다. 목록을 받을 변경·양쪽 변경·보낼 변경으로 나누며 **원격 변경 N개 가져오기(Pull)**는 로컬에서 수정하지 않은 원격 변경만 받습니다. CLI의 기본 `csync pull`도 같은 방식으로 동작합니다. 양쪽 수정·기준 확인 필요 문서는 건너뛰고 기존 파일과 기준을 유지하며, 다운로드 중 새 로컬 수정이 발생하면 기존 Pull 충돌 검사로 적용을 중단합니다. 자동 로컬 확인은 화면 전체의 busy 상태를 바꾸지 않으며 동일한 결과는 다시 그리지 않습니다. 마지막 조회 목록과 시각은 브라우저에 기준 폴더·참조 폴더별로 최근 5개까지 보관합니다. 새로고침 후 목록은 남고 이전 조회 결과라는 안내를 표시하며, 로컬 자동 재확인이 끝나기 전에는 선택 변경과 미리보기를 허용하지 않습니다. 업로드 승인·인증정보·diff 본문은 이 목록 캐시에 저장하지 않으며 조회 실패 때도 이전 목록을 유지합니다.
+
+웹에서는 **자동으로 갱신되는 목록 확인 → 필요하면 Fetch → 업로드할 문서 체크 → 업로드 미리보기 → 업로드** 순서로 진행합니다. 체크하면 즉시 업로드 대상에 포함되고 해제하면 제외됩니다. 체크 상태는 저장된 포함 여부를 나타냅니다. `변경 문서 모두 포함`·`모두 제외`로 일괄 변경하고, 포함 후 수정된 문서는 `최신 내용 반영`으로 다시 추가합니다. CLI와 같은 저장된 선택을 사용하며, 목록 조회와 선택 저장은 Confluence를 호출하지 않습니다. 삭제된 파일은 선택 해제로 정리하세요. Pull은 업로드 선택 목록과 독립적으로 동작합니다.
+
+기존 `csync push 문서.md`처럼 경로를 명시하면 그 경로를 즉시 선택해 처리합니다. 경로 없는 Push가 전체 범위로 확장되는 일은 없습니다. `push --list`는 작업공간의 문서 목록을 읽기만 합니다. 참조 폴더를 사용하면 `add`와 `push` 양쪽에 동일한 `--reference-root`를 지정하세요.
+
+## 원격 변경 확인 (Fetch)
+
+```bash
+csync fetch                    # 스페이스의 새 문서와 원격 변경 확인
+csync fetch --base ./스페이스   # 기준 폴더 지정
+```
+
+페이지별로 호출하지 않고 **스페이스 페이지 메타데이터를 100개씩 조회**해 새 문서와 버전·제목·부모 위치를 확인합니다. 새 문서 경로에 필요한 폴더 정보만 추가로 조회합니다. 본문과 첨부파일은 다운로드하지 않습니다. 결과는 `.csync/remote.json`에 저장하고 **2분 동안 캐시를 재사용**하며 조회 시각과 이번 API 요청 횟수를 표시합니다. 매핑·계정·연결 설정이 바뀌면 캐시를 다시 조회합니다. 한 실행은 최대 20회 요청으로 제한하고, 실패·제한 초과 시 기존 캐시를 유지합니다. `csync fetch --refresh`는 2분 캐시를 건너뛰고 다시 조회합니다.
+
+웹은 Push·Pull 성공 후 같은 작업 안에서 Fetch를 한 번 더 실행하고 변경 목록을 갱신합니다. 후속 Fetch는 캐시를 재사용하지 않으며, 완료될 때까지 로그와 로딩·작업 잠금을 유지합니다. 후속 Fetch만 실패했다면 Push·Pull 성공은 유지하고 별도 경고를 표시합니다.
+
+결과는 `원격 신규`, `버전 동일`, `원격 변경`, `조회 불가`, `확인 필요`로 구분합니다. 조회 결과에 없는 페이지를 삭제로 단정하지 않습니다. 새 문서 발견은 Fetch가, 실제 내용 반영은 Pull이 담당합니다. 페이지 버전이 그대로인 첨부 단독 변경은 감지하지 않습니다. `버전 동일`도 검사 시점의 페이지 메타데이터 비교 결과이며 전체 상태 일치를 보장하지 않습니다.
+
+Fetch는 문서와 `.csync/mapping.json`의 **기준 버전·해시를 변경하지 않습니다.** Push 충돌 검증이나 업로드 미리보기를 대신하지 않습니다. 웹에서는 문서 미리보기 아래의 독립된 **.env 연결 설정** 영역에서 연결 정보를 불러오고 스페이스에 연결한 뒤, 변경 문서 패널의 **원격 변경 확인(Fetch)**을 누르면 같은 CLI 명령으로 실행합니다. 조회 결과는 로컬 변경 목록과 합쳐 표시하고 자세한 요청 내역은 대상 및 실행 내역에 남깁니다. 자동 반복 조회는 하지 않습니다.
+
+## 변경된 문서만 Pull
+
+```bash
+csync fetch         # 새 원격 문서와 버전·위치 변경 확인
+csync status        # 로컬과 마지막 원격 조회 결과 확인
+csync pull          # 아직 받지 않은 문서와 안전한 원격 변경 받기
+```
+
+웹의 **가져오기 형식**에서 `Markdown`(기본) 또는 `Obsidian`를 선택합니다. 각각 `[이름](문서.md)`와 `[[문서|이름]]`으로 내부 링크를 기록하며, Obsidian 선택은 CLI의 `csync pull --obsidian`과 같습니다. 콜아웃 패널은 Markdown에서 제목이 있는 인용문으로, Obsidian에서 콜아웃으로 복원합니다. 두 방식 모두 `.md` 파일이며 표·첨부 저장 방식은 같습니다. 선택값은 브라우저에 저장되며 이후 가져오기와 복구·원복에 적용됩니다. 이미 받은 파일을 일괄 변환하지는 않습니다. 같은 파일명이 여러 개이거나 HTML 표 안의 링크는 상대 링크를 유지합니다. 일반 Markdown 링크도 Obsidian에서 사용할 수 있습니다.
+
+빈 작업공간과 기존 작업공간을 같은 규칙으로 처리합니다. 스페이스 페이지 메타데이터를 100개씩 조회하며 본문·첨부는 받지 않습니다. 경로 구성에 필요한 폴더만 추가 조회하고, 2분 이내 결과를 재사용합니다. 한 실행 최대 20회로 제한하며 불완전한 조회는 이전 캐시를 교체하지 않습니다. 원격 본문은 가져올 문서만 다운로드합니다.
+
+로컬 수정·로컬 삭제·이동 대기·양쪽 변경·기준 확인 필요 문서는 보존합니다. 매핑이 있는 누락 파일은 의도적인 로컬 삭제로 구분하며 원격 신규로 다시 받지 않습니다. 원격 조회 누락은 삭제로 단정하지 않고 해당 문서와 기준을 유지합니다. 로컬 경로가 겹치는 새 원격 문서도 덮어쓰지 않습니다. 다운로드는 임시 폴더에서 준비하고 충돌 검사 후 적용하며 실패한 임시 파일은 정리합니다. 문서·첨부 적용 후 기준 계산이나 저장이 실패하면 적용한 파일을 되돌리고 매핑을 유지합니다. 도중 추가 수정된 파일은 덮어쓰지 않으며 복원 자체가 실패하면 백업 경로를 안내합니다. 매핑은 임시 파일을 통해 교체합니다.
+
+페이지 버전이 그대로인 첨부 단독 변경은 메타데이터 조회만으로 감지하지 않습니다. 해당 문서를 갱신하려면 `csync restore 문서.md --overwrite`로 원격 본문과 참조 첨부를 다시 받을 수 있습니다. 이 경우 문서·첨부의 로컬 수정을 버리므로 원복 확인이 필요합니다.
+
+이전 실패로 Markdown만 남고 매핑이 없는 경우는 **받기 미완료 · 원격 대조 필요**로 표시하며, 업로드할 로컬 신규 문서로 취급하지 않습니다. Fetch 후 다시 가져오면 같은 경로·pageId·스페이스의 문서를 원격과 다시 대조합니다. 본문과 기존 첨부가 일치하는 경우만 원본 파일을 바꾸지 않고 기준을 복구하며, 다른 내용·다른 경로·다른 스페이스 문서는 보존합니다.
+
+원격에서 페이지가 다른 부모로 이동했다면 Pull 성공 시 그 부모 ID도 동기화 기준으로 기록합니다. 기존 로컬 파일 경로는 유지하면서 이미 받은 이동을 다음 Fetch에서 다시 변경으로 표시하지 않습니다. 새 원격 이동은 다시 감지하며 다운로드 실패 시 기준을 갱신하지 않습니다. 원격 diff는 frontmatter 뒤 구분용 빈 줄 하나를 제외해 비교하고 실제 본문 공백·원본 파일·로컬 변경 해시는 유지합니다.
+
+## 로컬 문서 복구와 수정 원복
+
+로컬 파일 삭제는 원격 삭제로 전파하지 않습니다. 기본 Pull은 로컬 삭제를 보존하므로, 누락된 문서를 최신 원격에서 다시 받으려면 파일을 직접 지정합니다.
+
+```bash
+csync restore README.md
+csync restore "지식자산/문서.md" --base ./스페이스
+csync status
+```
+
+매핑된 페이지 ID의 최신 본문·첨부만 읽으며 홈페이지 README를 복구해도 하위 페이지나 전체 스페이스를 탐색하지 않습니다. 기존 로컬 문서는 덮어쓰지 않고, 기존 첨부가 내려받은 내용과 다르면 충돌로 중단합니다. 다운로드 중 대상 파일이 새로 생긴 경우도 보존합니다. 제외 규칙·독립 작업공간·이동 대기와 동일 pageId의 다른 로컬 문서를 확인합니다.
+
+로컬에서 수정한 문서를 원격 최신으로 되돌리려면 `--overwrite`를 명시합니다.
+
+```bash
+csync restore "수정한 문서.md" --overwrite
+```
+
+**지정한 문서의 로컬 수정과 원격에서 참조하는 첨부의 로컬 수정이 사라집니다.** 다른 문서는 유지하며 불필요한 첨부를 삭제하지는 않습니다. 다운로드 중 파일이 추가로 변경되면 덮어쓰지 않고 중단합니다. 원격 버전이 로컬 기준과 같아도 명시적으로 원복할 수 있습니다.
+
+복구가 성공하면 해당 파일의 기준 버전·본문·원격 위치를 기록하고 업로드 선택에서 제외합니다. **복구한 README도 직접 `csync add README.md`로 선택하기 전에는 Push하지 않습니다.** `status`에는 누락 파일 옆에 복구 명령을 안내합니다. 원격 문서 생성·수정·삭제는 수행하지 않습니다.
+
+웹 Pull은 변경사항 위의 **원격 문서 n개 가져오기**로 실행합니다. 로컬이 비어 있어도 Fetch로 받을 문서를 확인한 뒤 같은 버튼을 사용합니다. 별도의 최초·전체 가져오기나 Push/Pull 방향 탭은 없습니다.
+
+웹에서는 **Confluence → 변경사항**의 각 문서 행에서 `원격에서 복구`(누락 문서) 또는 `원격으로 원복`(기존 문서)을 누릅니다. 확인창에 대상 경로와 덮어쓰기 범위를 표시하며, 취소하면 파일은 바뀌지 않습니다. 확인 후 공통 CLI 복구를 실행하고 목록·로딩·알림·실행 내역을 갱신합니다. 확인 이후 문서나 설정이 변경되면 다시 확인해야 합니다. 새 문서와 이동 중인 문서는 원격 원복 대상으로 표시하지 않습니다.
+
+## 파일 이동과 자동 매핑
+
+로컬 문서의 `pageId`를 유지한 채 파일을 옮기고 `push`하면, 기존 매핑에서 같은 페이지를 찾아 새 경로와 부모 위치를 자동으로 계산합니다. 별도 `remap` 실행은 필요하지 않습니다. 웹 미리보기·동기화도 같은 동작을 사용합니다.
+
+```bash
+# 로컬 파일·폴더 정리 후
+csync add .          # 이동한 문서를 업로드 대상에 추가
+csync push --dry-run  # 이동·본문 변경 계획 확인, 매핑 저장 없음
+csync push            # 원격 위치와 버전을 확인한 뒤 이동·갱신
+```
+
+같은 ID를 가진 파일이 둘이거나 이전 경로의 파일이 남아 있으면 중단합니다. 파일을 복사해서 새 페이지를 만들려면 복사본의 `pageId`를 제거하세요. 기존 페이지의 원격 버전 기준이 없으면 자동 이동도 차단하므로 로컬 편집을 보관하고 pull로 기준을 확보해야 합니다.
+
+`remap`은 별도 매핑을 가져오거나 원격 호출 없이 매핑만 저장하려는 고급 작업에 남겨둡니다.
+
+```bash
+csync remap --dry-run
+csync remap
+csync remap --base ./정리본 --from-mapping ./원본/.csync/mapping.json
+```
+
+- 기존 ID·제목·해시는 보존하고, 현재 경로에 따른 부모를 `pendingMove.parentKey`에 기록합니다. push 시 실제 부모와 비교해 이동하고 성공 후 대기 기록을 제거합니다.
+- 경로만 달라지고 렌더링 결과 해시가 같으면 본문·첨부 업로드 없이 이동합니다. 제목·본문·링크 변환 결과가 달라졌거나 기존 해시가 없으면 본문 갱신 대상이지만 원격 버전 기준이 없을 때는 차단합니다. `remap`은 새 해시를 만들어 변경을 숨기지 않습니다.
+- 매핑에 없는 상위 폴더는 같은 스페이스·부모·제목의 원격 폴더를 먼저 찾아 연결하고, 없을 때만 push 시 생성합니다. 폴더의 부모는 로컬 계층과 기존 매핑·스페이스 루트를 기준으로 결정합니다. 그 외 이름만 같고 부모가 다른 폴더는 재사용하지 않고 위치 충돌을 표시합니다. 폴더 검색과 메타데이터 조회 권한이 필요합니다. 생성 중 동명 충돌(400) 또는 충돌(409)이 나면 한 번 재조회해 같은 위치의 폴더를 재사용합니다. 매핑의 기존 폴더도 스페이스·제목·부모를 검증하며, 권한 오류나 위치 충돌은 자동 생성·이동으로 우회하지 않습니다. README가 있는 디렉토리는 해당 README 페이지가 부모입니다. 루트의 일반 문서는 스페이스 루트 아래에 연결됩니다. 업로드 선택 변경은 이동을 만들지 않으며 스페이스 홈페이지 자체는 이동할 수 없습니다.
+- 동일 ID를 가진 여러 문서나 매핑, 경로의 ID 충돌, 손상된 JSON은 저장 전에 거부합니다. 이동 대상 페이지 조회 실패 시 자동 재생성하지 않으며, 이동 실패 시 대기 기록을 유지합니다.
+- `--mapping`은 출력 매핑 위치, `--from-mapping`은 읽기 전용 원본 매핑입니다. `.csync/ignore`와 반복 `--exclude`를 지원합니다. 원본과 정리본을 함께 스캔하지 말고 정리본만 `--base`로 지정하세요.
+- ID가 없는 문서는 remap에서 미연결로 표시합니다. **이후 sync에서는 기존 규칙대로 새 페이지가 생성될 수 있으므로**, 관리용 문서는 ignore로 제외하세요.
+- 대상에 없는 기존 매핑은 유지합니다. 폴더 자체에는 frontmatter ID가 없으므로 폴더 ID의 경로 변경은 추론하지 않으며, 새 위치에는 새 폴더가 생성될 수 있습니다. 원격의 빈 폴더를 자동 삭제하지 않습니다.
+- 부모 페이지 이동은 원격 하위 페이지에도 영향을 줄 수 있습니다. `--dry-run`은 로컬 계획이며 원격 상태를 조회하지 않습니다. sync는 실행 시점의 로컬 트리를 기준으로 이동 계획을 다시 계산합니다.
+
+이동은 [Confluence의 페이지 이동 API](https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-content---children-and-descendants/#api-wiki-rest-api-content-pageid-move-position-targetid-put)를 사용합니다.
+
+## Push — Markdown → Confluence
+
+```bash
+confluence-sync push --list                 # 인식된 문서·제목·계층만 출력 (호출·인증 없음)
+confluence-sync add .                      # 작업공간 문서를 모두 선택
+confluence-sync push --dry-run              # 대상·상태(신규/변경/동일) 미리보기
+confluence-sync push                        # 추가한 문서의 변경만 갱신 (+ 신규 생성)
+
+confluence-sync push --base /abs/path/docs  # 동기화 루트 지정 (미지정 시 환경변수·상위 작업공간 탐색)
+confluence-sync push guide/                 # 지정 폴더만
+confluence-sync push guide/setup.md         # 단일 문서만 (상위 README 는 발행되지 않음)
+confluence-sync push --force                # 추가한 문서를 강제 갱신 (충돌 검사 유지)
+confluence-sync push --verify               # 변경 없는 문서도 원격 버전·존재 확인
+confluence-sync push --exclude '*-draft.md' # 제외 패턴 (반복 가능)
+```
+
+### 폴더 = 페이지 계층
+
+- 폴더의 **`README.md`** 가 그 폴더의 **대표 페이지**가 되고, 같은 폴더의 다른 문서는 그 자식이 됩니다.
+- README 가 **없는** 폴더는 **Confluence 폴더**로 생성되고 그 아래로 문서가 들어갑니다 (`write:folder` 스코프 필요).
+- `README.md` 는 폴더 맨 앞, 나머지는 파일명순(숫자 prefix `01-`, `10-` … 로 순서 제어)으로 정렬되어 부모가 자식보다 먼저 생성됩니다.
+
+> **경로를 지정해 동기화할 때**는 상위 `README.md` 가 **발행 대상이 아닙니다.** 자식을 붙일 부모 pageId 를 얻는 데만 쓰이고, 내용이 바뀌어 있어도 갱신하지 않습니다(`· 상위` 로 표시). 아직 페이지가 없으면 자식을 붙일 곳이 없으므로 그때는 생성합니다. 상위 문서도 갱신하려면 함께 지정하세요.
+
+```
+docs/                      → [스페이스 홈페이지]
+├── README.md              → 루트 페이지
+├── 10-guide/
+│   ├── README.md          → "10-guide" 대표 페이지
+│   └── 01-setup.md        → 그 자식 페이지
+└── 20-notes/              → README 없음 → Confluence 폴더
+    └── memo.md            → 폴더 안 페이지
+```
+
+### 변환 규칙
+
+- 페이지 제목은 **frontmatter `title` → 첫 `# 제목` → 파일명** 순으로 정해지고, 본문은 storage format 으로 변환됩니다.
+- 코드블록 → **code 매크로**, 표·리스트·헤딩은 그대로.
+- `mermaid` 코드블록 뒤에는 **Mermaid diagram** 매크로를 자동 삽입합니다. Confluence에 [Atlassian Labs Mermaid Diagrams Viewer](https://marketplace.atlassian.com/apps/1232887/mermaid-diagrams-viewer)가 설치되어 있어야 하며, 원본 코드도 함께 표시됩니다. 자동 연결은 등장 순서를 사용하므로 페이지의 모든 Mermaid 코드는 `mermaid` 코드블록으로 작성하세요.
+- **내부 `.md` 링크**와 **`[[wikilink]]`** → Confluence 페이지 링크로 자동 변환.
+- **섹션 링크** `[§1 개요](#1-개요)` · `[§6](./04-구현체.md#6-zkp)` · `[[문서#헤딩 텍스트]]` → Confluence 앵커 링크. [아래 참조](#섹션-링크-앵커)
+- **일반 파일 링크** `[자료](<attachments/자료.pdf>)` → PDF·TXT·MMD·JSON 등 실제 로컬 파일을 페이지 첨부로 업로드하고 다운로드 링크로 변환합니다. 경로는 Markdown 문서 위치 기준이며, 한글·공백 경로와 반복 링크를 지원합니다. 문서 링크(`.md`)·외부 URL·없는 파일은 기존 링크를 유지합니다. 같은 페이지에서 서로 다른 파일의 파일명이 같으면 업로드 이름에 경로 기반 접미사를 붙여 구분합니다.
+- **로컬 이미지**와 **`![[embed]]`** → 페이지 첨부로 업로드 후 참조 (같은 파일명은 새 버전으로 갱신). 외부 URL 이미지는 그대로.
+- **YAML frontmatter** 는 메타데이터로만 쓰이고 본문에 새지 않습니다.
+
+### 표 너비 지정
+
+일반 Markdown 표(`| … |`)에는 너비 문법이 없습니다. 짧은 번호·구분 열과 긴 설명 열의 너비를 다르게 지정하려면 `.md`에 HTML 표를 작성합니다. 전체 너비와 각 열 너비는 양의 픽셀 값으로 지정합니다.
+
+```html
+<table style="width: 760px;">
+  <colgroup>
+    <col style="width: 100px;" />
+    <col style="width: 660px;" />
+  </colgroup>
+  <tbody>
+    <tr><th>구분</th><th>설명</th></tr>
+    <tr><td>특허</td><td><strong>상세 설명</strong></td></tr>
+  </tbody>
+</table>
+```
+
+- Push는 전체 너비를 Confluence의 `data-table-width`에, 열 너비를 `colgroup`에 반영합니다. 전체 너비를 생략하고 모든 열 너비를 지정하면 합계를 사용합니다.
+- Pull은 원본 storage의 너비를 읽어 HTML 표로 보존합니다. `colspan`·`rowspan`이 지정된 표도 너비 지정 여부와 관계없이 HTML로 유지합니다. 너비와 병합 속성이 없는 표는 기존 GFM 표로 변환합니다. storage와 export_view의 표 개수가 다르면 storage 너비를 순서대로 적용하지 않고 export_view의 너비만 사용합니다.
+- 셀 안에서는 `**굵게**`, `[링크](파일)` 대신 `<strong>굵게</strong>`, `<a href="파일">링크</a>`를 씁니다. HTML 표 안의 문서·섹션 링크와 로컬 첨부 링크·이미지도 Push에서 처리합니다. Pull의 HTML 셀 안 링크는 `--obsidian`에서도 HTML 링크로 유지합니다.
+- 퍼센트 너비와 임의 CSS의 왕복 보존은 지원하지 않습니다. HTML·스타일 표시 여부는 Markdown 뷰어에 따라 다르며, Confluence 편집기의 실제 표시·재저장 결과는 별도 확인이 필요합니다.
+- 웹의 **문서 미리보기**는 파일 선택 시 Markdown·HTML 표를 렌더링합니다. **변환 미리보기**는 원본과 변환 결과의 소스를 비교합니다. 문서 미리보기는 1MB 이하 문서를 지원하며, 표 서식은 변경 비교 후 명시적으로 저장할 수 있습니다. 로컬 이미지는 기준 폴더 안의 PNG·JPEG·GIF·WebP·AVIF(개당 5MB 이하)를 표시합니다. 외부 이미지와 문서에 포함된 스크립트는 실행하지 않으며 Confluence의 실제 화면·붙여넣기 결과와 다를 수 있습니다.
+
+### 다른 동기화 폴더의 문서 링크
+
+`--reference-root`를 반복해서 지정하면 다른 동기화 폴더에 이미 게시된 문서로 연결할 수 있습니다.
+
+```bash
+csync push --base ./confluence-docs/project \
+  --reference-root ./confluence-docs/DBP \
+  --reference-root ./confluence-docs/shared \
+  ./confluence-docs/project/guide.md --dry-run
+```
+
+위키링크 `[[원본/긴/경로/문서명|표시 이름]]`와 Markdown 링크 `[표시 이름](../이전/문서명.md)` 모두 지원합니다. 현재 루트의 정확한 경로를 먼저 찾고, 참조 루트의 정확한 경로, 전체 후보의 파일명 순으로 검색합니다. 파일명 검색 결과가 하나일 때만 연결하며 별칭은 유지합니다. 현재 루트의 문서는 페이지 제목으로, 참조 문서는 `<참조 루트>/.csync/mapping.json`의 페이지 ID를 사용한 URL로 연결합니다.
+
+참조 폴더는 같은 Confluence 서버의 문서여야 합니다. 참조 폴더의 `.env`에 서버 주소가 있으면 현재 서버와 일치하는지 검사합니다. `.env`가 없으면 현재 서버의 매핑으로 간주합니다. 참조 문서와 매핑은 읽기만 하며 함께 업로드하지 않습니다. 제외 규칙도 적용합니다. 페이지 ID의 실제 서버 존재 여부는 미리보기에서 검사하지 않습니다.
+
+중복 파일명, 대상 문서 누락, 게시 매핑 누락은 CLI 출력과 웹 동기화 미리보기에 경고로 표시하고 링크 원문은 유지합니다. 경고는 업로드를 차단하지 않으므로 실행 전에 확인하세요. 다른 루트의 섹션 링크는 기존 앵커를 사용하며 참조 페이지에 앵커를 새로 만들지 않습니다.
+
+웹에서는 **Confluence → 추가 설정 → 참조 문서 폴더**에 한 줄씩 입력하거나 **참조 폴더 추가…**로 선택합니다. 설정은 새로고침 후에도 유지됩니다. 참조 폴더의 문서·매핑·설정이 변경되면 다시 미리보기해야 합니다. `convert`에는 이 옵션이 필요하지 않습니다.
+
+### 섹션 링크 (앵커)
+
+문서는 표준 마크다운 그대로 두면 됩니다. 이 도구가 Confluence 쪽 앵커를 만들어 맞춰 줍니다.
+
+**Confluence 가 헤딩에 자동으로 붙이는 id 에는 기대지 않습니다.** 그 규칙은 Cloud 와 Data Center 가 다르고(Cloud 는 공백만 하이픈으로 바꾸고, DC 는 `페이지제목-헤딩` 형태) 예고 없이 바뀌기 때문입니다. 대신 **링크 대상이 되는 헤딩 앞에 [Anchor 매크로](https://confluence.atlassian.com/doc/anchors-139442.html)로 이름(= 마크다운 슬러그)을 직접 심고** 링크가 그 이름을 가리키게 합니다 — 양쪽 다 이 도구가 정한 값이라 어느 배포판에서도 맞습니다. 실제로 가리켜지는 헤딩에만 심으므로 페이지가 지저분해지지 않습니다.
+
+| 쓰는 것 | Confluence 에서 |
+| --- | --- |
+| `[§1 개요](#1-개요)` | 같은 페이지의 그 헤딩으로 이동 |
+| `[[#1. 개요]]` · `[[#1. 개요\|§1]]` | 위와 동일 (Obsidian 표기) |
+| `[§6 ZKP](./04-구현체.md#6-zkp)` | 그 페이지의 그 헤딩으로 이동 |
+| `[[04-구현체#6. ZKP]]` | 위와 동일 (Obsidian 표기) |
+
+- 슬러그 규칙은 **GitHub 과 동일**합니다 — 소문자화 → 문자·숫자 아닌 것 제거 → 공백 하나당 하이픈 하나. 공백을 접지 않으므로 `제목  ·  블록` 의 `--` 도 그대로 맞습니다. 겹치는 헤딩에는 `-1`·`-2` 가 붙습니다.
+- 문서의 첫 `# H1` 을 가리키는 링크는 **페이지 최상단**이 됩니다 (H1 은 Confluence 페이지 제목이 되므로).
+- **대응하는 헤딩을 못 찾으면 링크를 바꾸지 않고 경고합니다.** 엉뚱한 섹션으로 보내는 대신 알려주는 쪽을 택했습니다 — 대개 오타나 깨진 상대경로입니다.
+
+```
+$ confluence-sync push --base ./docs --dry-run
+  [변경] guide/usage.md  →  "사용 안내"  (…, 내부링크: 36, 섹션링크: 30, 앵커: 15, 이미지: 0)
+  ⚠ 대응 헤딩 없는 앵커  guide/reference.md  #없는-헤딩
+```
+
+`섹션링크` 는 이 문서가 **가리키는** 링크 수, `앵커` 는 이 문서에 **심긴** 앵커 수입니다(다른 문서가 가리키는 것 포함).
+
+pull 은 반대로 Confluence 앵커를 마크다운 슬러그로 되돌립니다(`--obsidian` 이면 `[[문서#헤딩 텍스트]]`).
+
+### 변경 감지와 매핑
+
+- 문서의 `제목 + 본문 + 참조 첨부 내용` 해시를 저장해두고, **바뀐 문서만** 새 버전으로 올립니다(실제 sync는 위치·원격 버전을 조회한 뒤 `= 변경없음`으로 처리). `--force` 로 무시할 수 있습니다.
+- 매핑은 **`<base>/.csync/mapping.json`** 에 저장됩니다. **문서셋과 함께 커밋하세요** — 지우면 다음 실행에서 페이지가 중복 생성됩니다. (`--mapping <path>` 로 위치 변경 가능)
+- **pull 도 같은 매핑에 기록합니다** — 그래서 pull 직후 add 후 push 하면 `= 변경없음` 입니다. [Pull → 매핑 기록](#매핑-기록) 참고.
+- Confluence에서 페이지가 삭제됐거나 원격 버전이 달라졌다면 **중단하고 기존 매핑을 유지**합니다. 변경 없는 페이지까지 검사하려면 `--verify`를 사용합니다.
+
+### 동기화 제외 (로컬 전용 문서 유지)
+
+같은 폴더에 올릴 문서와 로컬에만 둘 문서가 섞여 있을 때 제외할 수 있습니다.
+
+- **`<base>/.csync/ignore`** — `.gitignore` 방식 패턴 파일 (문서셋과 함께 커밋)
+
+  ```gitignore
+  *-draft.md            # 초안 전부 제외
+  notes/local-only.md   # 특정 파일만 (notes/ 의 나머지는 동기화)
+  secret/               # 폴더 통째로
+  ```
+
+- **`--exclude <glob>`** — 일회성 제외 (반복 가능)
+
+제외된 문서는 list·dry-run·sync 모든 모드에서 빠지고, 그 문서만 있던 폴더는 생성되지 않습니다. 부정(`!`), `**` 등 `.gitignore` 규칙을 그대로 따릅니다.
+
+### v1의 `--rebuild` 이전 안내
+
+전체 삭제 후 재생성하던 `--rebuild`는 v2에서 제거되었습니다. 기존 페이지 ID를 유지하고, 파일을 옮긴 후 `push --dry-run`으로 확인해 `push`로 반영하세요. 본문을 강제로 다시 발행하려면 `push --force`를 사용합니다. 원격 충돌 검사는 유지되며 삭제·재생성하지 않습니다.
+
+
+## Pull — Confluence → Markdown
+
+```bash
+# .env가 있는 기준 폴더에서 실행
+confluence-sync fetch                   # 원격 신규·변경 문서 확인
+confluence-sync pull                    # 아직 없는 문서와 안전한 원격 변경 받기
+confluence-sync pull --obsidian         # 내부 링크를 위키링크로
+```
+
+- 로컬이 비어 있는 경우도 같은 Fetch/Pull로 처리합니다. 스페이스 홈페이지는 루트 `README.md`로 저장하며, 기존 문서는 매핑 경로를 유지합니다.
+- 새 문서는 원격 부모 관계로 경로를 정하고 필요한 폴더를 기록합니다. 본문 다운로드 전에 기존 로컬 경로와 제외 규칙·하위 작업공간 경계를 확인합니다.
+- 예전 `--full`·`--space`·숫자 ID·URL을 명시한 하위 트리 가져오기는 기존 스크립트 호환으로 유지합니다. 새 사용 흐름은 옵션 없는 Fetch/Pull입니다.
+- 새 작업공간은 해당 폴더에 `.env`를 준비하고 Pull하거나 `init --connect`로 연결하세요. `--base`와 `--out`은 같아야 합니다.
+- **누락된 원격 첨부**: 페이지의 첨부 목록에 없거나 다운로드가 404이면 원격 URL 참조를 유지하고 나머지 문서는 계속 가져옵니다. 로그에 페이지 ID·파일명과 누락 개수를 남기며 웹에는 **완료(경고)**로 표시합니다. 로그인·권한 오류(401/403), 네트워크·서버 오류는 누락으로 처리하지 않고 Pull을 중단합니다.
+- **이미지/첨부** 는 문서별로 `attachments/<문서명>/` 아래에 내려받고 링크를 그 경로로 씁니다 (문서 폴더가 이미지로 지저분해지지 않음). 다운로드에는 `read:attachment` 스코프가 필요합니다.
+- **내부 링크** 는 같은 실행에서 함께 받은 페이지끼리 **상대 `.md` 링크로 이어집니다.** Fetch 기반 Pull은 이번에 건너뛴 기존 로컬 문서로도 연결하며, 로컬에 없는 페이지는 절대 URL로 남습니다.
+- **섹션 링크** 는 Confluence 앵커(`#페이지제목헤딩텍스트`)를 그 문서의 **마크다운 슬러그로 되돌립니다** — 그대로 두면 Obsidian·GitHub 어디서도 걸리지 않기 때문입니다. `--obsidian` 이면 `[[문서#헤딩 텍스트]]` 로 씁니다.
+- 각 문서 머리에 **frontmatter** 가 붙습니다 — `title` · `pageId` · `spaceKey` · `source` · `updated`. `pageId` 가 다시 push 할 때의 앵커입니다.
+- 제목은 frontmatter 의 `title` 로만 들어가고 **본문에 `# 제목` 을 따로 넣지 않습니다** — 제목을 별도로 표시하는 뷰어(Obsidian 등)에서 두 번 보이기 때문입니다. push 는 `title` 을 먼저 읽으므로 왕복에 문제가 없습니다.
+- 본문은 `export_view`(HTML)를 [turndown](https://github.com/mixmark-io/turndown) 으로 변환합니다 — 코드블록(언어 포함, 미지정은 `plaintext`), GFM 표, 리스트 등.
+
+> **무손실 왕복은 아닙니다.** Confluence storage → Markdown 은 근사 변환이라 일부 매크로·레이아웃은 단순화됩니다.
+
+### 매핑 기록
+
+pull 은 받아온 문서를 **매핑 파일에 함께 기록합니다** — 페이지 id 와, push 가 계산하는 것과 **같은 방식의 변경 해시**를 남깁니다. 그래서 **pull 직후 add 후 push 하면 `= 변경없음`** 입니다. 이게 없으면 매핑에 해시가 없어 방금 받아온 내용을 그대로 되올려 보내게 됩니다.
+
+```bash
+$ confluence-sync pull --base ./docs
+  …
+완료  페이지 42개, 폴더 3개 생성  내부링크 88개 연결  매핑 45건
+  매핑: /repo/docs/.csync/mapping.json  (base: /repo/docs)
+
+$ confluence-sync push --base ./docs --dry-run
+  [동일] …          # 되올려 보낼 것이 없다
+```
+
+- **base는 `--out`의 상위 작업공간 또는 명시한 `--base`로 결정합니다.** 저장 위치는 기준 폴더의 원래 매핑 경로이며 `--out`과 `--base`는 같아야 합니다.
+- 연결 정보만 있는 폴더는 Pull에서 `.env`로 스페이스를 확인하고 작업공간을 연결합니다. 기존 사이트·스페이스 연결이 다르면 중단합니다.
+- **`--base <dir>`** · **`--mapping <path>`**로 위치를 지정할 수 있습니다. 매핑은 항상 유지하며 `--no-mapping`은 지원하지 않습니다.
+- 같은 페이지가 다른 키에 남아 있으면(문서를 옮겼으면) 옛 키를 걷어내 중복 항목을 만들지 않습니다.

package/docs/user/CONFIGURATION.md

@@ -0,0 +1,125 @@
+# 설정과 작업공간
+
+[← README로 돌아가기](../../README.md)
+
+설치, Confluence 인증, 작업공간 상태 파일과 기존 버전에서 이전하는 방법입니다.
+
+- [설치](#설치)
+- [API 토큰 발급](#api-토큰-발급)
+- [cloudId 확인](#cloudid-확인)
+- [빠른 시작](#빠른-시작)
+- [v2: 스페이스 작업공간](#v2-스페이스-작업공간)
+- [상태 파일 보관과 기존 파일 이전](#상태-파일-보관과-기존-파일-이전)
+- [v1에서 이전할 때](#v1에서-이전할-때)
+
+## 설치
+
+```bash
+npm i -g @wonseok-han/confluence-sync
+
+confluence-sync --version
+confluence-sync --help
+```
+
+Node.js 22.13 이상인 22.x 또는 24.x가 필요합니다.
+
+> 짧은 이름 **`csync`** 도 같이 설치됩니다 — 아래 예시의 `confluence-sync` 는 전부 `csync` 로 바꿔 쓸 수 있습니다.
+
+## API 토큰 발급
+
+웹의 **.env 연결 설정 → API 토큰 발급 가이드**에서 클릭 위치가 표시된 7단계 스크린샷과 권한 목록을 볼 수 있습니다. 상단 **사용 도움말 → API 토큰 발급**에서도 열 수 있습니다.
+
+1. https://id.atlassian.com/manage-profile/security/api-tokens → **Create API token with scopes**
+2. 앱 **Confluence** 선택
+3. 쓰려는 기능에 맞춰 스코프 선택:
+
+   | 기능 | 필요 스코프 |
+   | --- | --- |
+   | **스코프 조회·push 기본** (조회·생성·갱신) | `read:space` · `read:page` · `read:content-details` · `write:page` |
+   | 이미지/첨부 업로드 | `read:content-details` + `write:attachment` (둘 다) |
+   | README 없는 폴더를 Confluence 폴더로 생성 | `write:folder` |
+   | **pull** (읽기) | `read:page` + `read:content-details` |
+   | pull 시 첨부 이미지 다운로드 | `read:attachment` |
+
+   > 모두 `:confluence` 접미사가 붙습니다 (예: `read:page:confluence`).
+
+4. 토큰 계정은 대상 Space에 해당 권한이 있어야 합니다.
+
+## cloudId 확인
+
+`BASE_URL` 의 `<CLOUD_ID>` 는 아래에서 확인합니다.
+
+```
+https://<your-domain>.atlassian.net/_edge/tenant_info
+```
+
+## 빠른 시작
+
+```bash
+cd /path/to/docs          # 동기화할 .md 들이 있는 폴더
+
+confluence-sync init      # 대화형으로 .env 생성 (토큰 입력은 가려짐)
+confluence-sync init --connect --base . # Pull 없이 기존 문서 폴더 연결
+confluence-sync add .          # 작업공간 문서를 업로드 대상으로 선택
+confluence-sync push --dry-run # 무엇이 올라갈지 미리보기
+confluence-sync push           # 실제 발행
+```
+
+반대로 Confluence에서 가져오려면:
+
+```bash
+confluence-sync pull                      # 원격 신규·안전한 변경 받기
+```
+
+
+## v2: 스페이스 작업공간
+
+**기준 폴더 하나를 스페이스 전체의 로컬 작업공간으로 사용합니다.** 별도 파일·폴더 스코프 설정은 없습니다. Push는 직접 선택한 문서만 업로드하고, 기본 Pull은 원격에서만 바뀐 문서를 가져옵니다.
+
+```bash
+csync init                              # .env 생성 후 값 입력
+csync pull                              # 받을 원격 문서 가져오기
+csync fetch                             # 원격 메타데이터 확인
+csync pull                              # 원격에서만 바뀐 기존 문서 받기
+csync add "지식자산/특허출원/문서.md"     # 이 문서만 업로드 대상으로 추가
+csync push --dry-run --verify
+csync push
+```
+
+Pull 없이 구성한 로컬 폴더는 `.env`를 준비하고 `csync init --connect --base <폴더>`로 연결하세요. 새 문서도 `add` 후 Push할 수 있습니다. 기준 폴더 밖 경로는 거부하며 별도 백업 폴더의 문서를 쓰려면 그 폴더를 기준 폴더로 선택해야 합니다.
+
+기존 v2 설정의 로컬 `scope`·`syncPaths`는 필터로 사용하지 않습니다. 문서와 페이지 매핑은 유지하며, 재연결하면 예전 필터 필드를 제거합니다. 기존 원격 루트 연결은 임의로 바꾸지 않습니다. 예전에 스페이스의 일부 원격 폴더에 연결한 작업공간을 전체 스페이스로 확장하려면 별도 기준 폴더에 새로 Pull하세요. `CONFLUENCE_PARENT_ID`와 `init --scope`는 사용하지 않습니다.
+
+### 상태 파일 보관과 기존 파일 이전
+
+`.env`는 기존 위치에 두고 csync가 관리하는 파일은 `.csync/` 안에 모읍니다. 문서 경로와 매핑 키의 기준은 계속 작업공간 루트이며 `.csync/`로 바뀌지 않습니다.
+
+```text
+문서 루트/
+  .env
+  .csync/
+    mapping.json
+    workspace.json
+    ignore             # 선택: 제외 규칙
+  README.md
+  지식자산/
+```
+
+기존 루트의 `.confluence-sync.json`, `.confluence-workspace.json`, `.confluence-syncignore`도 계속 읽고 같은 위치에 저장합니다. 기존 파일을 모으려면 다음 명령을 명시적으로 실행하세요.
+
+```bash
+csync init --migrate --base . --dry-run
+csync init --migrate --base .
+```
+
+매핑 ID·해시·원격 버전·이동 대기·관리 범위와 제외 규칙의 내용을 그대로 복사하고 검증한 뒤 기존 파일을 제거합니다. `.env`와 문서·첨부는 이동하지 않으며 Confluence 호출도 없습니다. 양쪽 위치의 파일 내용이 다르면 덮어쓰지 않고 중단합니다. 중첩된 다른 작업공간은 이전하지 않습니다. 명시적인 `--mapping <path>` 경로는 계속 지원하며 자동 이전 대상이 아닙니다.
+
+### v1에서 이전할 때
+
+1. 문서·첨부·매핑·`.env`를 백업하고 미저장 로컬 변경을 별도로 보관합니다. 메타데이터 위치를 옮기려면 위 `init --migrate`를 사용합니다.
+2. `csync init --connect --base <실제 문서 루트>`로 스페이스에 연결합니다. 예전 부모 환경변수와 로컬 필터를 사용하지 않으며 기존 매핑은 유지합니다.
+3. **예전 매핑에는 `remoteVersion`이 없어 변경 업로드를 차단합니다.** `csync restore 문서.md --overwrite`로 원격 최신을 받아 기준을 확보하세요. 로컬 수정은 사라지므로 필요한 변경은 먼저 보관·비교하세요.
+4. 예전 `pull --space` 결과가 `<출력>/<스페이스>/`에 있고 매핑은 출력 바깥 기준이라면, 새 빈 `--out`에 받아 구조를 비교하세요. 기존 경로·설정을 자동 이동하거나 매핑을 추측해 재작성하지 않습니다. 이미 수동 보정한 문서 루트는 그대로 사용합니다.
+5. 하위에 별도 `.env`·매핑을 만든 기존 작업공간은 독립적으로 유지합니다. 자동 병합하지 않으므로 해당 하위 폴더를 `--base`로 지정해 사용할 수 있습니다. 새 작업공간에서는 스페이스 기준 폴더 하나와 업로드 문서 선택을 사용합니다.
+
+v1의 `pull --root`·`--no-mapping`은 지원하지 않습니다. 전체 탐색은 스페이스 **홈페이지의 하위 트리**이며 홈페이지 밖 별도 최상위 페이지까지 열거하지 않습니다.