사이트맵을 모듈·제품과 설계 현황으로 재편한다

README.md

@@ -28,7 +28,9 @@ stateless JSON Patch
 
 | 목적 | 위치 |
 | --- | --- |
-| 빠른 사용 예제 | [Intent guide](docs/public/intent-guide.md) |
+| 빠른 시작 | [설치·변경·구독](docs/public/quick-start.md) |
+| 모듈 찾기 | [책임별 API·Usage](docs/public/modules.md) |
+| 설계와 진행 상태 | [목표·프로토타입·소유권 감사](docs/public/design.md) |
 | 목표 구조와 TBD | [Architecture](docs/public/architecture.md), [Foundation](docs/public/foundation.md) |
 | JSON Document 개념 | [docs/public/overview.md](docs/public/overview.md) |
 | JSON Document Protocol | [docs/public/api.md](docs/public/api.md) |

audits/README.md

@@ -4,7 +4,7 @@
 ledger를 소유합니다. 사이트는 결과를 표시할 수 있지만 감사 계약과 판정은
 site-owned가 아닙니다.
 
-`document-types.json`의 후보 분모는 `site/site-routes.json`의 `Document Types`
+`document-types.json`의 후보 분모는 `site/site-routes.json`의 `/docs/document-types/*`
 서브 메뉴입니다. 모든 후보는 `candidateProfiles`에 필요성, 역할, 현재 관찰된
 schema와 근거 source symbol을 기록합니다. 이 schema는 감사 입력이며 정본 계약을
 미리 확정하지 않습니다. 후보를 감사할 때는 다음 순서로 닫습니다.

docs/README.md

@@ -25,31 +25,22 @@ docs
 복제한 탐색 정본이 아니다.
 
 ```text
-Introduction
-├─ Why
-├─ Architecture
-└─ How We Build
-Foundation
-├─ Overview
-├─ JSON Document Protocol
-├─ Document Types · TBD
-│  └─ 후보별 관찰된 schema·목표 owner·완료 증거
-├─ Editing Protocol
-│  └─ Intent · Topology · Selection · Clipboard · History
-└─ Collaboration
-   └─ Replica · Lifecycle · History · Text
-Building Blocks
-├─ Overview
-├─ Adapter
-├─ Connector
-├─ Affordance
-└─ UI Primitives
-Hands
-└─ 현재 Usage와 Official Hands Profile · TBD
-Artifact
-└─ Content Prototype · TBD
+시작하기
+├─ 소개 · 빠른 시작
+└─ Architecture
+모듈
+├─ JSON Document · Document Types · Editing · Collaboration
+└─ Adapter · Connector · Affordance · UI Primitives
+편집 조합 · Hands
+├─ 장르별 예제와 API
+└─ 지원 범위
 Applications
-└─ 제품 조합과 제품에서 발견한 책임
+└─ Bear · Calendar · AI Agent
+설계와 진행 상태
+├─ Artifact · Prototype
+├─ Official Hands 목표
+├─ 소유권 감사
+└─ 개발 원칙
 ```
 
 읽기 순서는 필수 package dependency chain이 아니다. Collaboration은 같은

docs/public/architecture.md

@@ -6,13 +6,14 @@
 사이트 등록에서 문서 URL·Usage·제품 관계를 읽습니다. 생성 API 본문은 각
 `packages/*/docs/api-reference.md`에 있습니다. 문서 목록을 별도로 복제하지 않습니다.
 
-- Foundation과 Building Blocks의 책임별 개요에서 모듈 API와 Usage를 찾습니다.
+- [모듈](modules.md)의 책임별 개요에서 API와 Usage를 찾습니다.
 - API 문서의 책임과 사용 경로에서 혼합 책임·이행 상태와 소비 제품을 확인합니다.
 - Usage의 Source에서 구현을 확인하고, 제품은 확인된 모듈 조합으로 돌아갑니다.
 - 패키지 공개 여부, Document Type 소유권 확정, Hand Profile 완료는 다른 상태입니다.
 
 목표는 같은 역할과 책임이 하나의 정본 모듈을 갖고, Application이 그 공개 API를
-조합하는 구조입니다. 아래는 읽기 순서와 책임 지도입니다. 모든 package가 차례로
+조합하는 구조입니다. 아래는 책임 지도입니다. 사이트의 읽기 순서는 시작하기·모듈·Hands·Applications·
+설계와 진행 상태이며, 책임 지도를 탐색 목적에 맞춰 투영합니다. 모든 package가 차례로
 의존하는 직렬 계층은 아닙니다.
 
 ```text
@@ -112,7 +113,7 @@ URL과 navigation, 권한·copy·fixture·layout과 concrete runtime 연결을 
 각 canonical module의 책임입니다. 한 제품에서만 쓰여도 이 경계는 같습니다.
 
 [Calendar와 AI Agent](applications.md)는 현재 제품에서 드러난 조합을 보여 줍니다.
-읽기 순서는 Foundation에서 Application으로 가지만, 책임을 발견하는 작업은
+책임 지도는 기반 계약부터 제품 조합까지 설명하지만, 책임을 발견하는 작업은
 Application에서 시작해 정본 API를 만들고 제품이 다시 소비하는 순환입니다.
 이 과정은 [How We Build](how-we-build.md)에 있습니다.
 

docs/public/design.md

@@ -0,0 +1,17 @@
+# 설계와 진행 상태
+
+현재 제공하는 모듈과 별개로, 아직 완성되지 않은 목표·프로토타입·소유권 경계를
+확인하는 곳입니다. API가 공개됐다는 사실과 Profile의 완료를 구분합니다.
+
+## 설계 목표
+
+- [Artifact · Prototype](/viewer): 여러 콘텐츠 surface를 조합한 시각적 실험입니다. 문서·Hands 계약 연결과 파일 호환성은 미완료입니다.
+- [Official Hands 목표](official-hands.md): 기본 편집을 완성된 SDK로 제공하기 위한 Profile 조건입니다.
+- [소유권 감사](ownership.md): Document Type 후보별 정본 소유자와 남은 경계를 확인합니다.
+- [개발 원칙](how-we-build.md): 제품에서 책임을 발견하고 정본 모듈로 반영하는 과정입니다.
+
+## 현재 제공하는 것
+
+바로 사용할 계약은 [모듈](modules.md), 장르별 실행 예제는 [Hands](hands.md),
+구체 제품 조합은 [Applications](applications.md)에서 찾습니다.
+목표 책임의 전체 관계는 [Architecture](architecture.md)에서 설명합니다.

docs/public/hands-support.md

@@ -0,0 +1,21 @@
+# 지원 범위
+
+Hands는 장르의 문서·편집·입력·UI를 조합한 편집 경험입니다.
+사용 가능한 예제와 API가 있어도 모든 입력·실패·History·호환성 조건을
+검증한 Official Hands Profile의 완료를 뜻하지 않습니다.
+
+## 확인하는 순서
+
+1. [장르별 예제](hands.md)에서 실제 편집 동작을 실행합니다.
+2. 해당 owner API에서 지원 입력과 연산, 제약을 확인합니다.
+3. Usage의 Source에서 정본 구현과 연결 방식을 확인합니다.
+4. [소유권 감사](ownership.md)와 [Official Hands 목표](official-hands.md)에서 남은 경계를 확인합니다.
+
+## 현재 근거
+
+- [Calendar](../../packages/json-document-calendar/docs/api-reference.md): 공개 Hand 계약과 [Calendar 예제](hands.md#calendar-editor)를 확인할 수 있습니다.
+- [Annotation](../../packages/json-document-annotation/docs/api-reference.md): 공개 Hand 계약과 [Annotation 예제](hands.md#annotation-editor)를 확인할 수 있습니다.
+- [Rich Text](/editing/rich-text): 문서·편집·Web·React를 연결한 대표 편집 조합입니다.
+- 다른 장르는 [Hands](hands.md)의 예제와 모듈 API에서 각각 지원 범위를 확인합니다.
+
+특정 장르의 검증 결과를 모든 Hands의 지원 보장으로 확대하지 않습니다.

docs/public/hands.md

@@ -1,5 +1,8 @@
 # Hands
 
+장르별 편집 예제와 공개 API를 확인합니다. [지원 범위](hands-support.md)에서
+현재 증거와 Profile 완료 조건을 구분하고, 설계 목표는 [설계 현황](design.md)에서 봅니다.
+
 ## Annotation editor
 
 Raster Annotation의 persistent model과 editing session은

docs/public/how-we-build.md

@@ -20,7 +20,7 @@ Application이 정본 API를 다시 소비한다
 읽기 순서와 책임을 발견하는 방향을 구별합니다.
 
 ```text
-읽기 순서: Foundation → Building Blocks → Hands → Artifact → Application
+읽기 순서: 시작하기 → 모듈 → Hands → Applications → 설계와 진행 상태
 책임 발견: Application → 책임 발견 → Canonical Module → Application
 ```
 

docs/public/llms.txt

@@ -11,7 +11,8 @@ reference·독립·collaboration binding에서 검증한다.
 
 ## 목표 구조와 현재 상태
 
-읽기 순서는 Foundation → Building Blocks → Hands → Artifact → Applications다.
+사이트 탐색은 시작하기 → 모듈 → 편집 조합 · Hands → Applications → 설계와 진행 상태다.
+Artifact·Official Hands 목표·소유권 감사는 설계 영역에 둔다.
 필수 package dependency chain이 아니다. Foundation은 JSON Document, Document
 Types, Editing, Collaboration을, Building Blocks는 Adapter, Connector,
 Affordance, UI Primitives를 묶는다. Adapter와 Connector는 독립적으로 선택한다.

docs/public/modules.md

@@ -0,0 +1,15 @@
+# 모듈
+
+필요한 책임에서 시작해 설명과 공개 API, 실행 가능한 Usage를 찾습니다.
+각 API의 Usage 링크에서 동작을 확인하고 Source 탭으로 구현을 따라갈 수 있습니다.
+
+## 선택 기준
+
+- 값·주소·변경·구독은 [JSON Document](api.md)를 사용합니다.
+- 문서의 의미와 유효성은 [Document Types](document-types.md), 편집 상태와 작업은 [Editing](editing.md)이 맡습니다.
+- 여러 참여자의 변경은 [Collaboration](collaboration.md), 플랫폼 입출력은 [Adapter](adapters.md)에서 찾습니다.
+- 외부 프레임워크·라이브러리는 [Connector](connectors.md), 조작 의미는 [Affordance](affordance.md), 반복 UI는 [UI Primitives](ui-primitives.md)가 맡습니다.
+
+장르별로 묶인 API와 예제는 [편집 조합 · Hands](hands.md)에 있습니다.
+전체 관계는 [Architecture](architecture.md), 미완료 목표와 소유권 감사는
+[설계와 진행 상태](design.md)에서 확인합니다. 메뉴 순서는 패키지 의존 순서가 아닙니다.

docs/public/overview.md

@@ -1,5 +1,8 @@
 # 왜 이 기반을 만드는가
 
+처음 사용한다면 [빠른 시작](quick-start.md), 필요한 계약은 [모듈](modules.md),
+목표와 미완료 상태는 [설계와 진행 상태](design.md)에서 찾을 수 있습니다.
+
 에이전트는 이제 답변만 생성하지 않습니다. 문서와 표, 발표 자료 같은
 artifact를 만들고, 사람은 그 결과를 곧바로 고쳐서 일을 이어 갑니다.
 생성될 artifact마다 예전 방식의 제품 FE를 따로 설계하고 구현할 수는 없지만,

docs/public/ownership.md

@@ -0,0 +1,13 @@
+# 소유권 감사
+
+아래 후보 상태는 기존 Document Type 감사 기록에서 읽습니다.
+소유권 확정은 전체 Profile이나 wire 계약의 Stable을 뜻하지 않습니다.
+
+## 상태 읽기
+
+- **소유권 확정 · RC**: 감사에서 해당 책임의 정본 소유자와 소비 경계를 확인했습니다.
+- **후보 · TBD**: 목표 계약과 현재 소유자가 아직 수렴하지 않았습니다.
+
+후보 이름을 눌러 현재 owner, 목표 경계와 감사 근거를 확인하세요.
+현재 제공하는 계약은 [Document Types](document-types.md),
+설계 목표 전체는 [설계와 진행 상태](design.md)에 있습니다.

docs/public/quick-start.md

@@ -0,0 +1,43 @@
+# 빠른 시작
+
+JSON Document는 값을 읽고 JSON Patch로 변경하는 공통 계약입니다.
+Core부터 사용하고, 편집 UI와 플랫폼 연결은 필요한 모듈을 추가합니다.
+
+## 설치
+
+```sh
+npm install @interactive-os/json-document
+```
+
+## 값 변경과 구독
+
+```ts
+import { createJSONDocument } from "@interactive-os/json-document";
+
+const document = createJSONDocument({ title: "첫 문서" });
+const unsubscribe = document.subscribe(() => {
+  console.log(document.value);
+});
+
+document.commit([{ op: "replace", path: "/title", value: "수정한 문서" }]);
+console.log(document.at("/title"));
+unsubscribe();
+```
+
+읽기·검증·변경·구독의 세부 계약은 [JSON Document](api.md),
+공개 symbol은 [Core API](../../packages/json-document/docs/api-reference.md)에서 확인합니다.
+
+## 직접 실행하기
+
+아래 Usage에서 값을 바꾸고 Source 탭에서 정본 구현을 확인하세요.
+
+```live-demo
+/demo
+```
+
+## 다음 선택
+
+- 입력·선택·실행 취소를 붙이려면 [Editing](editing.md)을 봅니다.
+- React나 스키마 라이브러리를 연결하려면 [Connector](connectors.md)를 봅니다.
+- 장르별 편집 경험은 [Hands](hands.md), 제품 조합은 [Applications](applications.md)에서 확인합니다.
+- 전체 책임은 [모듈](modules.md), 관계와 경계는 [Architecture](architecture.md)에서 찾습니다.

packages/json-document-calendar/docs/api.md

@@ -0,0 +1,7 @@
+## Calendar Hand와 편집 계약
+
+Calendar Hand는 React lifecycle과 viewport·입력·UI 조합을 제공합니다.
+시간·반복·거절의 의미는 UI에서 다시 정의하지 않고 정본 Editing 계약을 소비합니다.
+
+[시간·반복·거절 계약: Editing의 Calendar protocol profile](/docs/api/editing#calendar-protocol-profile-rc)에서
+지원 범위와 실패 시 문서·선택·History 보존 조건을 확인하세요.

site/scripts/check-document-type-audits.mjs

@@ -6,7 +6,7 @@ const root = new URL("../..", import.meta.url).pathname;
 const ledger = JSON.parse(readFileSync(join(root, "audits/document-types.json"), "utf8"));
 const allowed = new Set(["canonical consumer", "Host composition", "duplicate implementation", "canonical API gap", "missing canonical module", "mislocated module", "out of scope", "unverified"]);
 const expectedCandidates = siteRoutes
-  .filter((route) => route.navigationGroup === "Document Types" && route.path.startsWith("/docs/document-types/"))
+  .filter((route) => route.path.startsWith("/docs/document-types/"))
   .map((route) => route.path.slice("/docs/document-types/".length));
 
 if (JSON.stringify(ledger.candidates) !== JSON.stringify(expectedCandidates)) throw new Error("Document Type audit candidates do not match the TBD navigation denominator");

site/scripts/route-checks.mjs

@@ -1,6 +1,7 @@
 const routePathPattern = /^\/(?:[a-z0-9]+(?:-[a-z0-9]+)*\/?)*$/;
 const navigationGroups = new Set([
   "Introduction",
+  "Design",
   "JSON Document",
   "Document Types",
   "Collaboration",