# 겹 사용 가이드

이 문서는 겹의 실제 기능을 기준으로 작성된 사람 및 AI용 사용 설명서입니다.

## 시작하기

계정을 만들고 첫 워크스페이스와 페이지를 구성합니다.

### 계정과 공개 체험

로그인 없이 공개 체험을 시작하거나 정식 계정을 만들어 개인 데이터를 계속 보관할 수 있습니다.

1. 홈에서 체험하기를 누르면 최대 10페이지의 임시 공개 워크스페이스가 열립니다.
2. 정식 사용은 회원가입 후 로그인합니다. 이메일 인증이 켜진 서버에서는 인증까지 마쳐야 합니다.
3. 프로필에서 표시 이름, 사진, 이메일, 비밀번호와 로그인 세션을 관리합니다.

### 워크스페이스 만들기

워크스페이스는 페이지, 멤버, 채팅과 권한을 묶는 가장 큰 작업 단위입니다.

1. 사이드바 상단의 워크스페이스 이름을 눌러 새 작업 공간을 선택합니다.
2. 이름과 아이콘을 정하면 첫 페이지가 자동으로 생성되고 즉시 열립니다.
3. 설정에서 이름 변경, 멤버 초대, 소유권 이전, 나가기 또는 삭제를 수행합니다.

> 팁: 업무·개인·프로젝트처럼 권한과 문서가 실제로 분리되어야 할 때 새 워크스페이스를 만드세요.

### 페이지와 사이드바

페이지를 계층으로 정리하고 즐겨찾기·최근 문서·검색으로 빠르게 이동합니다.

1. 새 페이지 작성 또는 페이지 행의 + 버튼으로 최상위·하위 페이지를 만듭니다.
2. 페이지를 다른 페이지 중앙에 놓으면 하위 페이지, 위·아래 경계에 놓으면 순서 이동이 됩니다.
3. 별표로 즐겨찾기에 추가하고 검색창에서 제목이나 내용을 찾아 이동합니다.

## 에디터와 블록

텍스트부터 고급 블록까지 겹 문서를 작성합니다.

### 기본 작성과 슬래시 명령

본문에서 바로 입력하고 / 또는 + 버튼으로 블록 명령을 검색합니다.

- 제목, 본문, 인용, 글머리·번호 목록, 할 일, 구분선, 코드 블록과 표를 지원합니다.
- 텍스트를 선택하면 굵게, 기울임, 밑줄, 취소선, 코드와 링크 도구가 나타납니다.
- 슬래시 메뉴는 키보드 방향키와 Enter로도 선택할 수 있습니다.

### 드래그, 재정렬과 열

6점 핸들로 블록 순서를 바꾸거나 좌우 드롭 영역에 놓아 열을 만듭니다.

1. 블록 왼쪽의 6점 핸들을 잡아 세로 삽입선 위치로 이동합니다.
2. 다른 블록 좌우 영역에 잠시 두면 열 배치 안내가 나타납니다.
3. 사이드바 페이지나 데이터베이스 행에 놓으면 해당 페이지 끝으로 블록이 이동합니다.

> 팁: 터치 환경에서는 블록 메뉴의 ‘다른 페이지로 이동’을 사용하면 같은 결과를 얻을 수 있습니다.

### 고급 블록

콜아웃, 토글, 탭, 목차, 파일·이미지, 코드, 캔버스, 데이터베이스와 일정 블록을 사용할 수 있습니다.

- 목차는 문서의 H1~H4 제목을 자동으로 추적합니다.
- 이미지와 파일은 붙여넣기 또는 드래그로 추가하고 이미지 크기를 조절할 수 있습니다.
- 캔버스는 카드와 연결선을 자유 배치하는 독립 작업 화면을 제공합니다.
- 페이지 블록은 실제 하위 페이지를 문서 안에 표시하며 사이드바와 같은 컨텍스트 메뉴를 사용합니다.

### Markdown 가져오기와 내보내기

일반 Markdown과 겹 Markdown을 붙여넣거나 전체 문서를 복사·내보낼 수 있습니다.

- 붙여넣을 때 일반 텍스트, 서식 유지 또는 Markdown 변환을 선택할 수 있습니다.
- 겹 Markdown은 데이터베이스, 캔버스, 하위 페이지 같은 고급 구조도 표현합니다.
- AI Blueprint Studio에서 프롬프트를 만들고 결과를 검증·미리보기한 뒤 빈 페이지에 적용할 수 있습니다.

## 데이터베이스

같은 데이터를 여러 보기와 연결 블록에서 관리합니다.

### 데이터베이스 만들기

표, 보드, 목록, 갤러리, 캘린더, 타임라인 등의 보기에서 같은 행 데이터를 다룹니다.

1. 슬래시 메뉴에서 데이터베이스를 추가하고 이름과 첫 보기를 정합니다.
2. 속성을 추가해 텍스트, 선택, 날짜 등 행의 구조를 정의합니다.
3. 보기마다 필터, 정렬, 그룹과 표시 속성을 따로 설정합니다.

### 행은 하나의 페이지

각 데이터베이스 행은 제목과 속성뿐 아니라 전체 문서 본문을 가진 페이지입니다.

- 행을 클릭해 팝업으로 빠르게 편집하거나 전체 페이지로 열 수 있습니다.
- 표·보드·캘린더 등 어느 보기에서 수정해도 같은 원본 행에 반영됩니다.
- 일반 블록을 행에 드롭해 행 페이지 본문으로 이동할 수 있습니다.

### 연결 데이터베이스

원본 데이터베이스를 선택해 다른 페이지에 양방향 실시간 연결 블록을 만듭니다.

1. 연결 데이터베이스 블록을 추가하고 원본 문서 또는 연결 코드를 선택합니다.
2. A·B·C 블록이 같은 원본을 가리키면 어느 블록에서 수정해도 모두 반영됩니다.
3. 각 연결 블록은 필요한 보기를 선택하되 행과 속성은 원본과 공유합니다.

> 팁: 블록의 ‘원본 · 데이터베이스명’ 태그로 어떤 원본과 연결됐는지 확인할 수 있습니다.

## 캘린더와 일정

개인 일정, 문서 일정과 데이터베이스 날짜를 한곳에서 봅니다.

### 캘린더와 일정 만들기

사이드바의 일정에서 캘린더를 만들고 월간 보기에서 일정을 추가합니다.

1. 빈 날짜를 클릭하면 하루 일정을, 여러 날짜를 드래그하면 연속 종일 일정을 만듭니다.
2. 제목, 시작·종료, 시간대, 종일 여부, 장소, 설명, 반복, 참석자와 알림을 입력합니다.
3. 일정을 드래그해 날짜를 바꾸고 우클릭으로 열기, 복제 또는 삭제합니다.

### 문서의 일정 블록

슬래시 메뉴의 일정 블록으로 캘린더의 동일한 이벤트를 문서 안에 붙입니다.

- 블록과 캘린더 화면은 같은 이벤트 원본을 사용하므로 양쪽 수정이 즉시 동기화됩니다.
- 회의록이나 프로젝트 페이지에 관련 일정만 골라 표시할 때 유용합니다.

### 공유, 구독과 외부 캘린더

다른 사용자에게 편집자·뷰어 권한을 주거나 공개 캘린더를 구독할 수 있습니다.

- 캘린더 설정에서 사용자를 검색해 공유하고 역할을 정합니다.
- 다른 사용자의 공개 캘린더를 구독하면 내 일정 화면에 함께 표시됩니다.
- ICS 내보내기는 Google Calendar, Samsung Calendar 등 RFC 5545 호환 앱에서 가져올 수 있습니다.
- Google Calendar 직접 양방향 연결을 위한 외부 ID·etag·sequence 구조는 준비되어 있으며 OAuth 동기화는 별도 설정 범위입니다.

## 협업과 권한

워크스페이스와 개별 페이지를 안전하게 함께 편집합니다.

### 워크스페이스 역할

소유자, 권한 관리자, 편집자, 뷰어 역할로 접근 범위를 나눕니다.

- 소유자(owner): 모든 문서·멤버·권한·소유권·삭제를 관리합니다.
- 권한 관리자(manager): 멤버 초대와 하위 권한 조절 및 문서 편집이 가능합니다.
- 편집자(editor): 페이지와 콘텐츠를 만들고 수정할 수 있습니다.
- 뷰어(viewer): 읽기만 가능하며 생성·편집·드래그 작업은 차단됩니다.

### 개별 페이지 공유

워크스페이스 전체가 아닌 특정 페이지 트리만 뷰어 또는 편집자로 공유합니다.

- 페이지 공유 설정에서 사용자를 검색하고 역할과 복사 허용 여부를 선택합니다.
- 하위 페이지는 가장 가까운 공유 루트의 권한을 상속합니다.
- 공유받은 사용자는 협업 공간에서 직접 나갈 수 있습니다.

### 실시간 편집, 상태와 채팅

동료의 접속 상태와 편집 위치를 보고 워크스페이스·개인 채팅으로 대화합니다.

- 페이지 상단의 사용자 버블을 누르면 상대가 보고 있는 페이지로 이동합니다.
- 변경은 실시간으로 공유되며 저장 버전 충돌 시 최신 서버 문서를 확인할 수 있습니다.
- 채팅은 전체, 워크스페이스, 개인 대화로 구분되고 사용자 검색 규칙을 공통으로 사용합니다.

## 검색과 문서 관리

많아진 문서를 찾고 관계·버전·휴지통을 관리합니다.

### 검색과 그래프

검색으로 페이지를 찾고 그래프에서 페이지와 데이터베이스 관계를 탐색합니다.

- 사이드바 검색은 제목과 접근 가능한 문서를 빠르게 찾습니다.
- 그래프 화면과 우측 미니 그래프는 페이지 링크와 관계를 시각화합니다.
- 마우스 휠은 그래프 줌, 드래그는 이동이며 페이지 스크롤과 분리됩니다.

### 버전 기록과 휴지통

이전 문서 버전을 확인하고 삭제한 페이지 트리를 복원하거나 영구 삭제합니다.

- 페이지 메뉴의 버전 기록에서 저장 시점별 제목과 본문을 확인합니다.
- 삭제는 먼저 휴지통으로 이동하며 하위 페이지도 함께 보존됩니다.
- 휴지통에서 원래 위치로 복원하거나 영구 삭제할 수 있습니다.

## 공개와 발행

링크 공유부터 둘러보기·검색 노출까지 공개 범위를 관리합니다.

### 비공개, 링크 공개, 전체 공개

페이지별 공개 범위를 정하고 하위 페이지·실시간 보기 옵션을 조절합니다.

- 비공개는 권한이 있는 사용자만 볼 수 있습니다.
- 링크 공개(unlisted)는 주소를 아는 사람만 볼 수 있고 검색·둘러보기 노출은 꺼집니다.
- 전체 공개(public)는 둘러보기, 검색엔진 색인과 공개 댓글을 선택적으로 켤 수 있습니다.

### 둘러보기와 SEO

공개 글을 겹 둘러보기에 게시하고 검색 결과와 공유 카드 정보를 다듬습니다.

- 자동 제목·설명·이미지를 사용하거나 수동 SEO 메타데이터를 입력합니다.
- 검색엔진 색인을 허용한 공개 글은 sitemap 대상이 됩니다.
- 내 공개 콘텐츠 대시보드에서 여러 글을 선택해 노출·댓글·공개 상태를 일괄 변경합니다.

## 모바일과 PWA

휴대폰·태블릿·Samsung DeX에서 겹를 앱처럼 사용합니다.

### 홈 화면에 설치

Chrome 또는 Samsung Internet의 앱 설치 기능으로 겹를 독립 창에서 실행합니다.

1. 브라우저 메뉴에서 ‘앱 설치’ 또는 ‘홈 화면에 추가’를 선택합니다.
2. 설치된 앱은 기존 로그인 상태를 유지하고 전체 화면에 가까운 환경으로 열립니다.
3. 앱 첫 화면에서 뒤로가기를 한 번 누르면 종료 안내가 나오며 2초 안에 다시 누르면 종료됩니다.

### 터치 편집

모바일에서는 블록 메뉴, 페이지 선택기와 길게 누르기를 이용해 정밀 작업을 수행합니다.

- 드래그가 어려우면 블록 메뉴의 이동·복제·삭제 기능을 사용합니다.
- 대화상자와 워크스페이스 설정은 모바일 화면 안에서 스크롤됩니다.
- 글꼴 크기는 프로필의 표시 설정에서 기기별로 조절할 수 있습니다.

## 계정 보안과 API

세션과 API 키를 관리하고 AI 자동화를 안전하게 연결합니다.

### 로그인 세션 관리

프로필에서 접속 기기, IP, 사용자 에이전트와 마지막 사용 시각을 확인하고 세션을 끊습니다.

- 모르는 세션은 즉시 해제하고 비밀번호도 변경하세요.
- 비밀번호 변경과 계정 비활성화는 모든 로그인 세션과 API 키를 함께 해제합니다.

### API 키와 AI 자동화

API와 AI 화면에서 읽기·쓰기·삭제 범위와 만료 기간을 정해 키를 발급합니다.

1. AI 또는 자동화마다 별도 이름의 키를 만들고 필요한 권한만 선택합니다.
2. 워크스페이스 생성·설정·삭제·소유권·멤버 관리는 workspaces:manage, 공개·둘러보기·SEO·댓글 관리는 publications:manage 권한을 별도로 켭니다.
3. 데이터베이스·캘린더·댓글·파일·사용자 검색·친구·채팅·변경 제안·자동화는 각각 분리된 권한을 필요한 경우에만 추가합니다.
4. 글로벌 관리자에게만 회원 조회·생성·수정·역할·감사 로그 권한이 별도 운영자 범위로 표시됩니다.
5. AI에게 공개 API 가이드 주소를 제공하고 키는 Secret 또는 환경 변수로 전달합니다.
6. 사용이 끝났거나 유출이 의심되면 키를 즉시 폐기합니다.

> 팁: 키 원문은 생성 직후 한 번만 표시되고 서버에는 해시만 저장됩니다.

### 운영자 전용 API 권한

회원 관련 자동화는 일반 API 키와 분리되고 현재 글로벌 관리자만 사용할 수 있습니다.

- 회원 조회, 회원 생성, 회원 상태 수정, 글로벌 역할 변경, 감사 로그 조회가 각각 별도 권한입니다.
- 글로벌 역할 변경에는 회원 수정과 역할 관리 권한이 동시에 필요합니다.
- 운영자 권한이 하나라도 포함된 키는 최대 30일만 발급되며 강등 시 기존 키도 사용할 수 없습니다.
- API 회원 생성은 기본적으로 키당 시간당 5회로 제한되고 실패 요청도 한도에 포함되며, 성공한 생성은 감사 로그에 남습니다.
- 공개 회원가입은 서버 설정으로 완전히 닫을 수 있으며, 허용 중에도 IP별 가입 제한이 적용됩니다.

> 팁: AI에는 승인한 계정의 정확한 수와 식별자만 전달하고 임의 계정 생성을 허용하지 마세요.

### AI의 안전한 정밀 편집

검색·트리·블록 ID·버전 diff와 승인 제안을 이용해 AI가 필요한 범위만 수정하도록 합니다.

- 문서 전체를 교체하기 전에 블록 목록에서 안정적인 blockId를 읽고 한 블록만 삽입·교체·이동·삭제할 수 있습니다.
- 모든 노트 쓰기는 expected_version, 일정 수정은 expected_sequence로 사람의 최신 변경을 보호합니다.
- 영향이 큰 변경은 drafts:write로 미리보기 제안을 만들고 별도 승인 권한으로 적용합니다.
- 여러 노트 작업은 dry_run으로 검증한 뒤 원자적 배치 또는 백그라운드 작업으로 실행합니다.

### 변경 피드, Webhook과 MCP

AI 에이전트가 변경을 추적하거나 겹 도구를 직접 발견해 호출하도록 연결합니다.

- 변경 피드는 30일간 커서 순서로 제공되어 마지막 처리 위치부터 다시 읽을 수 있습니다.
- Webhook은 공개 HTTPS 주소와 HMAC 서명을 사용하고 반복 실패 시 자동으로 비활성화됩니다.
- MCP 엔드포인트는 API 키가 가진 권한의 도구만 노출하며 REST와 같은 권한·충돌·요청 제한을 적용합니다.
- 전체 요청·응답 규격은 사람용 API 가이드, AI 원문과 OpenAPI JSON에서 확인합니다.

## 문제 해결

자주 만나는 저장·이동·권한 문제를 확인합니다.

### 다른 변경이 먼저 저장됨

같은 문서를 여러 창이나 클라이언트에서 수정해 버전이 달라졌을 때 나타나는 보호 메시지입니다.

1. 현재 편집 내용을 복사해 보존합니다.
2. 안내의 최신 서버 문서 열기로 다른 탭에서 변경 사항을 비교합니다.
3. 필요한 내용을 병합한 뒤 최신 버전에서 다시 저장합니다.

### 페이지가 열리지 않거나 편집할 수 없음

워크스페이스 역할, 페이지 공유, 휴지통 상태와 로그인 세션을 순서대로 확인합니다.

- 뷰어는 읽기만 가능하므로 소유자 또는 권한 관리자에게 편집자 권한을 요청합니다.
- 공유에서 제거되거나 워크스페이스를 나가면 열린 실시간 연결도 즉시 종료됩니다.
- 페이지가 휴지통에 있으면 일반 주소에서 열리지 않으므로 휴지통에서 복원합니다.

### 드래그가 의도한 위치에 놓이지 않음

삽입선·좌우 열 안내·페이지 테두리가 나타난 뒤 놓고, 터치에서는 메뉴 이동을 사용합니다.

- 페이지 중앙은 하위 이동, 위·아래 경계는 순서 변경입니다.
- 데이터베이스 행에는 일반 블록을 넣을 수 있지만 페이지 자체 이동은 제한됩니다.
- 창 가장자리에서는 자동 스크롤 후 드롭 안내가 안정된 위치에서 놓으세요.

## 개발자 API

- 사람용 API 가이드: /developers/api
- AI용 API 원문: /developers/api/ai-guide.txt
- API 키 관리(로그인 필요): /user/api