@roottale/cms-mcp 0.53.1 → 0.56.0

package/docs/content-models-and-exposures.md

@@ -1,36 +1,339 @@
 ---
-title: 콘텐츠 모델과 노출 슬롯
-description: 페이지·글·정보 모델과 배너·팝업을 고객 FRONT에 연결하는 방법
+title: 콘텐츠 모델과 노출 관리
+description: 페이지·글·정보 모델, 확장 필드, 배너·팝업을 API·MCP·CLI로 관리하는 방법
 ---
 
-# 콘텐츠 모델과 노출 슬롯
+# 콘텐츠 모델과 노출 관리
 
-RootTale은 운영 화면의 콘텐츠를 세 가지로 나눕니다.
+RootTale의 콘텐츠 관리 단위는 다음과 같습니다.
 
-- 페이지: 개발자가 주소와 화면을 만들고 운영자가 내용을 수정합니다.
-- 글: 운영자가 항목을 만들며 목록·상세 주소가 있습니다.
-- 정보: 인물·서비스·후기처럼 구조화된 값을 운영자가 만들고, 화면은 개발자가 정합니다.
+| 리소스 | 뜻 | 안정 식별자 |
+|---|---|---|
+| 콘텐츠 모델 | 페이지·글·정보의 구조와 화면 연결 | `model_key` |
+| 필드 그룹 | 모델에 붙는 구조화된 추가 필드 | `model_key` + `group_key` |
+| 항목 | 모델에 속한 실제 페이지·글·정보 | `post_id` |
+| 노출 슬롯 | FRONT가 선언한 배너·팝업 위치 계약 | `slot_key` |
+| 노출 캠페인 | 슬롯에 표시할 내용·기간·경로 | `exposure_id` |
 
-고객 FRONT는 `fetchContentModels()`로 활성 모델을 읽고, `fetchPosts({ modelKey })`로
-특정 모델의 항목만 가져올 수 있습니다. 기존 `fetchCollections()`와
-`collectionKey`는 지원 기간 동안 그대로 동작합니다.
+`source: "code"`인 모델·필드 그룹은 개발자 계약입니다. 구조를 API로 바꾸거나
+삭제할 수 없습니다. 모델 상태만 활성화·비활성화할 수 있습니다.
+`source: "site"`인 리소스는 관리 API로 만들고 수정할 수 있습니다.
 
-```ts
-import { fetchContentModels, fetchPosts } from "@roottale/cms-client/server";
+## 권한
 
-const models = await fetchContentModels({ apiKey: process.env.ROOTTALE_API_KEY! });
-const people = await fetchPosts({
-  apiKey: process.env.ROOTTALE_API_KEY!,
-  modelKey: "people",
-  limit: 20,
-});
+전체 자동화에는 API 키 프로필 `full_management`를 권장합니다. 세부 권한은
+다음과 같이 분리됩니다.
+
+| 권한 | 허용 작업 |
+|---|---|
+| `cms:read` | 모델·필드·항목·노출 슬롯·캠페인 조회 |
+| `cms:write` | 항목 작성·수정·삭제 |
+| `cms:publish` | 항목 발행·발행 취소 |
+| `content-models:write` | site 모델·필드 그룹 관리, code 모델 상태 변경 |
+| `exposures:write` | 노출 캠페인 초안 작성·수정 |
+| `exposures:publish` | 노출 발행·보관, 발행 중 캠페인 수정 |
+
+이전 키 프로필에는 새 쓰기 권한이 자동으로 추가되지 않습니다. 자동화에 필요한
+권한을 명시해 새 키를 발급하세요.
+
+## 콘텐츠 모델과 필드 그룹
+
+모델 API:
+
+- `GET|POST /v1/cms/content-models`
+- `GET|PATCH|DELETE /v1/cms/content-models/{model_key}`
+- `GET|POST /v1/cms/content-models/{model_key}/field-groups`
+- `GET|PATCH|DELETE /v1/cms/content-models/{model_key}/field-groups/{group_key}`
+
+수정·삭제는 응답의 `updated_at`을 `expected_updated_at`으로 다시 보내야 합니다.
+다른 사용자가 먼저 바꿨다면 `409 version_conflict`가 납니다. 사용 중인 모델과
+필드 그룹은 삭제할 수 없습니다.
+
+```json
+{
+  "key": "team-member",
+  "label": "구성원",
+  "cardinality": "collection",
+  "preset": "entity",
+  "presentation": {
+    "kind": "detail",
+    "detailPath": "/team/:slug",
+    "templateKey": "team-member"
+  },
+  "publication": null,
+  "definition": {}
+}
+```
+
+필드 그룹의 `definition`은 필드 배열과 검증 규칙을 담습니다. 정의되지 않은
+`field_values` 키, 형식이 틀린 값, 다른 사이트 항목을 가리키는 관계 값은 저장되지
+않습니다.
+
+## 계층형 분류 모델
+
+FAQ·도움말·문서처럼 목록 아래에 여러 단계의 분류 허브가 필요한 모델은
+`presentation.kind: "category_tree"`를 사용합니다. 이 계약은 FAQ 전용 기능이
+아니며 1~3단계 분류를 지원합니다.
+
+```json
+{
+  "key": "faq",
+  "cardinality": "collection",
+  "preset": "article",
+  "presentation": {
+    "kind": "category_tree",
+    "basePath": "/faq",
+    "categoryDepth": 2,
+    "templateKey": "faq"
+  }
+}
+```
+
+### 목록·피드 규칙도 모델이 소유합니다
+
+글 목록의 카테고리 모음, RSS 피드, 허브 주소 형식처럼 예전 `collections`
+설정에만 있던 규칙은 이제 `detail`·`category_tree` presentation의 선택 필드로
+선언합니다. 모두 생략 가능하며 기본값은 컬렉션이 없을 때의 동작과 같습니다.
+
+| 필드 | 의미 | 기본값 |
+|---|---|---|
+| `archives` | 카테고리 모음 주소(`{목록}/categories/{slug}` 또는 direct)를 발행·갱신 | `false` |
+| `feed` | RSS 피드에 포함 | `false` |
+| `categoryPath` | 카테고리 허브 주소 형식 — `namespaced` = `{목록}/categories/{slug}`, `direct` = `{목록}/{slug}` | `namespaced` |
+| `layout` | 목록 레이아웃 힌트(FRONT가 해석, 라우팅과 무관) | 없음 |
+
+`detail`의 목록 주소는 `detailPath`에서 `/:slug`를 뗀 부모 경로이고,
+`category_tree`는 `basePath`가 목록입니다. 예전 `collections` 응답은 호환을 위해
+유지되지만 새 사이트는 모델 presentation만 읽으면 됩니다.
+
+**RootTale 표준 블로그 주소** — RootTale이 만드는 사이트(스타터·`roottale init` 시드)의
+`blog` 모델은 아래 규칙 하나를 씁니다: 글 `/blog/{category}/{slug}`, 카테고리 허브
+`/blog/{category}`, 목록 `/blog`. 1단계 `category_tree`이고 글마다 카테고리를 정확히
+하나 고릅니다(`categoryCardinality: "exactly-one"`). 옛 평면 주소 `/blog/{slug}`와
+`/blog/categories/{slug}`는 FRONT가 정본으로 301 합니다.
+
+```json
+{
+  "kind": "category_tree",
+  "basePath": "/blog",
+  "categoryDepth": 1,
+  "templateKey": "blog",
+  "categoryPath": "direct",
+  "categoryCardinality": "exactly-one",
+  "archives": true,
+  "feed": true
+}
+```
+
+직접 만드는 사이트가 평면 상세 주소를 유지해도 됩니다 — 그때는 `detail` 규칙을
+선언하고 FRONT 라우트를 그 규칙에 맞추면 됩니다.
+
+```json
+{
+  "kind": "detail",
+  "detailPath": "/blog/:slug",
+  "templateKey": "blog",
+  "archives": true,
+  "feed": true
+}
+```
+
+공개 사이트는 `fetchCategories({ collectionKey: "faq" })`의 `id`와 `parentId`로
+루트부터 말단까지의 분류 사슬을 만들고, `fetchPosts({ modelKey: "faq" })`의 글마다
+말단 카테고리를 정확히 하나 연결합니다. 위 예시는 다음 주소를 표현합니다.
+
+- `/faq`
+- `/faq/headache`
+- `/faq/headache/migraine`
+- `/faq/headache/migraine/{slug}`
+
+ROOT-ADMIN은 발행·예약 시 선언한 깊이의 말단 분류인지 다시 검사합니다. 부모만
+고르거나 복수 분류를 연결한 항목은 발행하지 않습니다. 분류 `slug`나 부모 관계를
+바꾸는 일은 공개 주소 변경이므로 기존 발행 글이 있으면 일반 라우팅 변경 보호를
+따릅니다.
+
+코드로 배포하는 모델은 `editor`에서 저장 구조를 바꾸지 않고 ROOT-ADMIN의 기본
+필드 이름과 분류 단계 이름만 바꿀 수 있습니다.
+
+```json
+{
+  "editor": {
+    "labels": {
+      "title": "질문",
+      "excerpt": "짧은 답변",
+      "body": "상세 답변",
+      "categories": "질환 분류",
+      "tags": "검색 태그"
+    },
+    "categoryLevels": ["진료 영역", "세부 질환"]
+  }
+}
+```
+
+`categoryLevels`의 개수는 `categoryDepth`와 같아야 합니다. 최종 선택에서는 말단
+분류 ID 하나만 기존 카테고리 관계로 저장됩니다.
+
+관계형 커스텀 필드는 `postType`과 함께 `modelKey`를 지정하면 선택 대상을 같은
+콘텐츠 모델로 좁힐 수 있습니다. 예를 들어 `relationship` 필드에
+`"postType": "post", "modelKey": "faq"`를 선언하면 관련 FAQ만 표시됩니다.
+
+아직 CMS에 글이나 초안이 없는 미래 콘텐츠는 `textarea`에 내부 콘텐츠 키 형식을
+선언해 예약할 수 있습니다. ROOT-ADMIN은 전용 입력기에서 접두사·중복·최대 개수를
+검사하며, 저장 API도 같은 규칙을 적용합니다. 값은 공개 `fields`에 줄바꿈 문자열로
+그대로 제공되므로 고객 FRONT가 현재 발행 원장과 대조해 링크 노출을 결정합니다.
+
+```json
+{
+  "key": "field_related_content_keys",
+  "name": "related_content_keys",
+  "label": "미발행 FAQ 예약 키",
+  "type": "textarea",
+  "format": "internal_content_keys",
+  "keyPrefix": "faq",
+  "maxItems": 5
+}
+```
+
+키는 `faq.headache.migraine.aura-symptoms`처럼 영문 소문자·숫자·한글과 점·
+하이픈으로 구성합니다. `keyPrefix`를 주면 해당 접두사로 시작하는 키만 저장할 수
+있습니다. 이 필드 자체는 미발행 URL을 만들지 않습니다.
+
+### 본문 안의 예약 내부 링크
+
+글 본문에서는 다른 글을 텍스트 표기로 연결할 수 있고, 아직 발행되지 않은 글도 미리
+연결해 둘 수 있습니다.
+
+```text
+[[internal:{키}|표시 문구]]
+```
+
+**키는 대상 글의 정규 공개 경로 조각을 점으로 이은 것**입니다. 경로는 사이트맵·
+단축링크와 같은 규칙으로 정해지므로 콘텐츠 유형에 관계없이 한 규칙입니다.
+
+| 공개 경로 | 키 |
+|---|---|
+| `/faq/headache/migraine/aura-symptoms` (계층형 분류 모델) | `faq.headache.migraine.aura-symptoms` |
+| `/column/headache/my-post` (카테고리 주소 컬렉션) | `column.headache.my-post` |
+| `/blog/my-post` (일반 컬렉션) | `blog.my-post` |
+| `/team/hong` (상세 프리셋 모델) | `team.hong` |
+
+고정 페이지·`data_only` 모델처럼 글별 상세 주소가 없는 콘텐츠는 대상이 되지 않습니다.
+
+ROOT-ADMIN 편집기 도구 모음의 **내부 링크 삽입** 버튼이 이 표기를 대신 만들어
+줍니다. 작성자는 콘텐츠 유형과 분류를 이름으로 고르고 글(초안 포함)을 목록에서
+고르거나, 아직 없는 글의 slug만 적습니다. 각 글의 게시 주소 영역에는 다른 글에서
+이 글을 연결할 때 쓰는 키가 복사 버튼과 함께 표시됩니다.
+
+이 표기는 본문 `body_json`의 일반 텍스트로 저장되며 공개 API도 그대로 내보냅니다.
+해석은 고객 FRONT의 몫입니다 — 텍스트 구간에서 표기를 찾아, 현재 발행 원장의 글
+경로를 같은 규칙으로 키로 바꿔 대조한 뒤 있으면 링크로, 없으면 표시 문구만
+렌더링하세요. `code`·`pre`·이미 링크된 구간과 속성값은 변환하지 않는 것을 권장합니다.
+
+**글의 주소는 계산하지 말고 읽으세요.** 공개 글 응답의 `path`(`@roottale/cms-client`
+에서는 `post.path`)가 플랫폼이 저장한 정규 공개 경로입니다(예 `/column/my-post`,
+상세 주소가 없는 글은 `null`). 링크·사이트맵·내부 링크 키에 이 값을 그대로 쓰면
+모델 규칙이 바뀌어도 FRONT 코드를 고칠 필요가 없습니다. 내부 링크 키는 이 경로의
+조각을 점으로 이은 값과 같습니다.
+
+**주소가 바뀐 글도 자동으로 따라가게 하려면** 공개 글 응답의 `previous_slugs`(옛 slug
+목록, 최신순 — `@roottale/cms-client`에서는 `previousSlugs`)를 함께 쓰세요. 현재 경로의
+마지막 조각을 옛 slug로 바꾼 경로도 같은 글의 키로 등록하면, `[[internal:blog.old-slug|…]]`
+처럼 옛 키로 남아 있는 본문도 현재 주소로 렌더됩니다(분류 이동은 이력이 없어 대상 밖).
+
+## 페이지·글·정보 항목
+
+항목 API는 기존 `/v1/cms/posts`를 그대로 쓰며 모든 응답에 `model_key`와
+`field_values`가 포함됩니다.
+
+```json
+{
+  "model_key": "team-member",
+  "title": "홍길동 세무사",
+  "slug": "hong-gildong",
+  "body_json": {"type":"doc","content":[]},
+  "field_values": {
+    "position": "대표 세무사",
+    "specialties": ["법인세", "상속세"]
+  }
+}
 ```
 
-## 배너·팝업
+- `page` 모델은 `type: "page"`, `article`·`entity` 모델은 `type: "post"`로
+  저장됩니다. `model_key`와 `type`이 다르면 요청을 거부합니다.
+- `entity` 항목에는 작성자·카테고리·태그를 붙일 수 없습니다.
+- 작성자를 사용하는 `article` 모델은 발행·예약 전에 활성 공개 작성자가 필요합니다.
+- 기존 자동화가 `model_key`를 생략하면 활성 page/article 모델이 정확히 하나일 때만
+  호환 처리됩니다. 후보가 여러 개면 `400 model_key_required`입니다.
+- 항목의 모델은 생성 뒤 바꿀 수 없습니다. 다른 모델로 옮기려면 새 항목을 만드세요.
 
-운영자는 임의 위치에 팝업을 만들 수 없습니다. 개발자가 사이트 콘텐츠 계약에
-등록한 슬롯 안에서만 내용·기간·대상 경로·우선순위를 관리합니다. FRONT는 슬롯을
-코드에 명시하고 `RootTaleExposureSlot`을 놓습니다.
+공개 FRONT는 검증된 표시 값 `fields`를 읽습니다. 관리 자동화는 편집 가능한 원문
+`field_values`를 사용합니다.
+
+## 노출 슬롯과 캠페인
+
+노출 슬롯은 FRONT의 사이트 콘텐츠 계약에서 옵니다. 관리 API로 슬롯을 만들거나
+수정할 수 없습니다.
+
+- `GET /v1/cms/exposure-slots`
+- `GET|POST /v1/cms/exposures`
+- `GET|PATCH /v1/cms/exposures/{exposure_id}`
+- `POST /v1/cms/exposures/{exposure_id}/publish`
+- `POST /v1/cms/exposures/{exposure_id}/archive`
+
+생성은 항상 초안입니다. 수정·발행·보관은 `version`을 확인합니다. 발행 응답의
+`overlap`은 같은 슬롯·경로·기간에 겹치는 캠페인 수와 ID를 알려 줍니다. 겹침은
+오류가 아니며, 공개 FRONT는 우선순위와 최신순 규칙으로 한 건을 선택합니다.
+
+```json
+{
+  "slot_key": "global-popup",
+  "kind": "popup",
+  "content": {"variant":"notice","title":"여름 휴무 안내"},
+  "starts_at": "2026-08-20T00:00:00.000Z",
+  "ends_at": "2026-08-25T00:00:00.000Z",
+  "target_paths": ["/"],
+  "priority": 10,
+  "repeat": "session"
+}
+```
+
+## MCP와 CLI
+
+MCP는 각 HTTP 작업을 같은 이름의 도구로 제공합니다.
+
+- 모델: `listCmsContentModels`, `getCmsContentModel`, `createCmsContentModel`,
+  `updateCmsContentModel`, `activateCmsContentModel`, `deactivateCmsContentModel`,
+  `deleteCmsContentModel`
+- 필드: `listCmsFieldGroups`, `getCmsFieldGroup`, `createCmsFieldGroup`,
+  `updateCmsFieldGroup`, `activateCmsFieldGroup`, `deactivateCmsFieldGroup`,
+  `deleteCmsFieldGroup`
+- 항목: `listManagedCmsPosts`, `getManagedCmsPost`, `createCmsPost`,
+  `updateCmsPost`, `publishCmsPost`, `unpublishCmsPost`, `deleteCmsPost`
+- 노출: `listCmsExposureSlots`, `listCmsExposures`, `getCmsExposure`,
+  `createCmsExposure`, `updateCmsExposure`, `publishCmsExposure`,
+  `archiveCmsExposure`
+
+CLI의 큰 JSON 입력은 camelCase 키를 쓰는 `--input-file`로 전달합니다.
+
+```bash
+npx -y @roottale/cms-mcp cli models list
+npx -y @roottale/cms-mcp cli models create --input-file ./model.json
+npx -y @roottale/cms-mcp cli fields create team-member --input-file ./fields.json
+npx -y @roottale/cms-mcp cli entries create \
+  --model-key team-member --title "홍길동" --slug hong-gildong \
+  --body-file ./body.json --field-values-file ./values.json
+npx -y @roottale/cms-mcp cli exposure-slots list
+npx -y @roottale/cms-mcp cli exposures create --input-file ./exposure.json
+npx -y @roottale/cms-mcp cli exposures publish "<exposure-id>"
+```
+
+`posts`는 기존 스크립트 호환 별칭입니다. 새 자동화는 `entries`를 권장합니다.
+
+## 공개 FRONT 연결
+
+고객 FRONT는 `fetchContentModels()`와 `fetchPosts({ modelKey })`로 활성 모델과
+항목을 읽습니다. 노출은 개발자가 `RootTaleExposureSlot`을 배치한 위치에만
+표시됩니다.
 
 ```tsx
 import { RootTaleExposureSlot } from "@roottale/cms-renderer-next/server";
@@ -42,22 +345,16 @@ export default async function Layout({ children }: { children: React.ReactNode }
       apiKey={process.env.ROOTTALE_API_KEY!}
       slotKey="global-popup"
       path="/"
-      allowedVariants={["card", "image-card"]}
+      allowedVariants={["notice"]}
       revalidate={60}
     />
   </>;
 }
 ```
 
-알 수 없는 variant, 계약에서 제거된 슬롯, 발행 기간 밖 캠페인은 렌더하지 않습니다.
-팝업은 닫기 버튼과 Escape 닫기를 제공하고 `always|session|day|never` 재노출 정책을
-적용합니다. `@roottale/cms-renderer-next/styles`를 root layout에서 한 번 불러오세요.
-
-## Raw API
+공개 raw API는 다음 세 경로입니다.
 
 - `GET /v1/cms/public/content-models`
-- `GET /v1/cms/public/posts?model_key=people`
+- `GET /v1/cms/public/posts?model_key=team-member`
+- `GET /v1/cms/public/categories?collection_key=faq` (`id`, `parent_id` 포함)
 - `GET /v1/cms/public/exposures?slot_key=global-popup&path=%2Fabout`
-
-모두 고객용 API key와 `cms:read` 범위가 필요합니다. 노출 API는 선택된 공개 내용만
-반환하며 초안, 보관함, 내부 일정·타기팅 원문은 반환하지 않습니다.

package/docs/custom-redirects.md

@@ -17,6 +17,11 @@ description: 어드민 "설정 > 주소 이동"에서 정의한 임의 경로
 - **커스텀 리다이렉트(이 문서)** — 글이 아닌 임의 경로를 옮깁니다. 라우팅
   *이전* 단계인 **미들웨어**에서만 가로챌 수 있어, 아래 설정이 필요합니다.
 
+글의 공개 주소가 바뀌면(slug 변경·분류 이동·모델 규칙 변경) 플랫폼이 옛 경로 → 현재
+경로 301 을 **자동으로** 이 목록에 더합니다(`id` 가 `path-history:` 로 시작). 운영자가
+같은 출발 경로 규칙을 만들었으면 운영자 규칙이 이깁니다. 미들웨어를 쓰고 있다면 별도
+작업 없이 옛 링크가 새 주소로 갑니다.
+
 규칙은 `GET /v1/cms/public/redirects` 로 내려오며 **활성** 규칙만 포함됩니다
 (`api-reference.md`). 출발 경로는 정규화된 사이트 내부 절대 경로, 도착지는
 내부 경로 또는 절대 URL, 상태는 `301`(영구) 또는 `302`(임시)입니다.

package/docs/getting-started.md

@@ -137,10 +137,11 @@ console.log(page.items.map((p) => p.slug));
 
 `401` 에러(`invalid_key`)면 키 값/환경변수 로딩을 확인하세요.
 
-## 5. MCP로 글과 이미지 자동화
+## 5. MCP로 전체 CMS 자동화
 
-MCP 설정의 `ROOTTALE_API_KEY`에 `read_write` 키를 넣으면 다음 tool을 쓸 수
-있습니다.
+MCP 설정의 `ROOTTALE_API_KEY`에 `full_management` 키를 넣으면 모델·필드·항목·
+노출·미디어 도구를 모두 쓸 수 있습니다. 글과 이미지만 관리한다면 기존
+`read_write` 키로 충분합니다.
 
 1. `getSiteKnowledge`로 브랜드 보이스와 금지어 확인
 2. `uploadCmsMedia`로 썸네일 또는 본문 삽화 업로드
@@ -148,6 +149,11 @@ MCP 설정의 `ROOTTALE_API_KEY`에 `read_write` 키를 넣으면 다음 tool을
 4. 필요하면 `setCmsPostTerms`로 카테고리·태그 연결
 5. 검토 후 `publishCmsPost`로 발행
 
+정보 모델을 새로 자동화할 때는 `createCmsContentModel` →
+`createCmsFieldGroup` → `createCmsPost(modelKey, fieldValues)` 순서로 진행합니다.
+배너·팝업은 `listCmsExposureSlots`로 FRONT 계약을 먼저 읽고
+`createCmsExposure` → `publishCmsExposure` 순서로 진행합니다.
+
 썸네일은 업로드 응답의 `id`를 `featuredMediaId`에 넣습니다. 본문 삽화는
 응답의 `url`을 Tiptap image 노드에 넣습니다.
 
@@ -175,31 +181,35 @@ export ROOTTALE_API_KEY=rtlk_cust_xxxxxxxxxxxxxxxxxxxxxxxx
 npx -y @roottale/cms-mcp cli media upload ./thumbnail.webp \
   --alt "글 대표 이미지"
 
-npx -y @roottale/cms-mcp cli posts create \
+npx -y @roottale/cms-mcp cli entries create \
   --title "새 글" \
   --slug "new-post" \
   --body-file ./post.json \
   --featured-media-id "<업로드 응답의 id>"
 
-npx -y @roottale/cms-mcp cli posts publish "<글 id>"
+npx -y @roottale/cms-mcp cli entries publish "<글 id>"
 ```
 
-상위 `cli --help`는 `posts`, `media` 그룹만 보여줍니다. 전체 하위 명령은
+상위 `cli --help`는 `models`, `fields`, `entries`, `exposure-slots`,
+`exposures`, `media` 그룹을 보여줍니다. 전체 하위 명령은
 다음 도움말에서 확인하세요.
 
 ```bash
-npx -y @roottale/cms-mcp cli posts --help
+npx -y @roottale/cms-mcp cli entries --help
+npx -y @roottale/cms-mcp cli models --help
+npx -y @roottale/cms-mcp cli exposures --help
 npx -y @roottale/cms-mcp cli media --help
 
 # 특정 명령의 모든 옵션
-npx -y @roottale/cms-mcp cli posts create --help
+npx -y @roottale/cms-mcp cli entries create --help
 npx -y @roottale/cms-mcp cli media upload --help
 ```
 
-글 명령은 `list`, `create`, `update`, `publish`, `unpublish`, `set-terms`,
+항목 명령은 `list`, `get`, `create`, `update`, `publish`, `unpublish`,
+`set-terms`, `delete`,
 미디어 명령은 `list`, `upload`, `update`, `delete`를 제공합니다.
 
-내부 운영 저장소에서는 같은 기능을 `rt cms posts ...`,
+내부 운영 저장소에서는 같은 기능을 `rt cms entries ...`,
 `rt cms media ...` 명령으로도 실행할 수 있습니다.
 
 ## 다음 단계

package/docs/revalidation-webhooks.md

@@ -12,7 +12,13 @@ description: 글 발행/수정 시 사이트 캐시를 near-real-time으로 갱
 - 별도 webhook secret을 보관할 필요가 없습니다 — 검증은 사이트 스코프 API
   키로 JWKS 공개키를 가져와 수행합니다.
 - ISR `revalidate = 1800` 같은 시간 기반 설정은 **fallback**입니다. 정상
-  경로는 웹훅입니다.
+  경로는 웹훅입니다. 웹훅이 실패하면(타임아웃·5xx·연결 오류) 플랫폼이 변경을
+  outbox 에 남겨 1·2·4분… 간격(최대 6시간, 8회)으로 자동으로 다시 보내고,
+  어드민 "발행 알림 기록" 화면에서 즉시 다시 보낼 수도 있습니다 — 사이트가
+  잠시 내려가 있어도 변경은 유실되지 않습니다. 웹훅 배선이 끝난 사이트는 fallback 을 길게 잡아도
+  됩니다(`sites/starter` 는 6시간, `21600`) — 짧게 잡으면 방문이 있는 페이지마다
+  그 주기로 재생성이 일어나 함수 실행·ISR 쓰기·API 호출이 늘어날 뿐, 정상
+  반영 속도는 웹훅이 정합니다.
 
 ## 1. revalidate 라우트 추가 (Next.js)
 

package/docs/seo.md

@@ -415,6 +415,59 @@ const crumbs = breadcrumbSchema([
 발행 웹훅의 `alsoRevalidate`에 `/feed.xml`, `/sitemap.xml`을 포함해 글 변경
 시 함께 갱신하세요 (`revalidation-webhooks.md` 참고).
 
+## 메인 홈 메타데이터 (홈 제목·홈 설명)
+
+어드민 **설정 > 검색·공유 표시 > 메인 홈 검색 노출**에서 저장한 홈 제목·홈
+설명은 `fetchBlogSettings().siteProfile.homeTitle` / `homeDescription` 으로
+내려옵니다(공개 API `site_profile.home_title` / `home_description`). 홈(`/`)
+라우트의 `generateMetadata` 에서 이 값을 우선 쓰고, 비어 있으면(null) 사이트
+이름(`fetchTheme().siteName`)·사이트 설명(`siteProfile.siteDescription`)으로
+폴백하세요. `title` 은 root layout 의 `%s | 사이트명` 템플릿을 타지 않도록
+`{ absolute }` 로 넘깁니다. `openGraph` 는 page 값이 layout 값을 통째로
+대체하므로 `siteName`·`images` 까지 다시 채웁니다.
+
+```tsx
+// app/page.tsx
+import type { Metadata } from "next";
+import {
+  BLOG_SETTINGS_CACHE_TAG,
+  fetchBlogSettings,
+  fetchTheme,
+  THEME_CACHE_TAG,
+} from "@roottale/cms-client/server";
+
+const apiKey = process.env.ROOTTALE_API_KEY!;
+
+export async function generateMetadata(): Promise<Metadata> {
+  const [theme, settings] = await Promise.all([
+    fetchTheme({ apiKey, tags: [THEME_CACHE_TAG] }).catch(() => null),
+    fetchBlogSettings({ apiKey, tags: [BLOG_SETTINGS_CACHE_TAG] }).catch(() => null),
+  ]);
+  const siteName = theme?.siteName ?? "예시 사이트";
+  const profile = settings?.siteProfile;
+  const title = profile?.homeTitle ?? siteName;
+  const description = profile?.homeDescription ?? profile?.siteDescription ?? undefined;
+  const image = profile?.defaultOgImageUrl ?? undefined;
+  return {
+    title: { absolute: title },
+    description,
+    alternates: { canonical: "/" },
+    openGraph: {
+      type: "website",
+      siteName,
+      title,
+      description,
+      ...(image ? { images: [image] } : {}),
+    },
+  };
+}
+```
+
+어드민에서 저장하면 서버가 `theme.updated` 알림을 보내므로 `revalidation-
+webhooks.md` 의 태그 배선(`BLOG_SETTINGS_CACHE_TAG`)이 되어 있으면 홈
+제목·설명이 곧바로 반영됩니다. `sites/starter` 는 `buildHomeMetadata()`
+(`components/SiteRootShell.tsx`)로 같은 동작이 이미 배선돼 있습니다.
+
 ## 글 메타데이터 (canonical·robots·OG)
 
 블로그 글 상세의 `generateMetadata` 에서 어드민 SEO 패널(`metaJson.seo`) 값을
@@ -473,6 +526,15 @@ return buildPostMetadata(post, {
 seo?: PostSeoOverrides }).seo` 로 넘기세요. `path` 는 redirect 후의 **현재
 slug**(`post.slug`) 기준으로 주세요(아래 301 참고).
 
+**canonical 경로 우선순위(ADR-0105)** — `path` 옵션 → 글의 저장된 정규 공개 경로
+(`post.path`, 원본 post 나 `path`·`collectionKey`·`modelKey` 를 함께 넘기면 자동) →
+`collections` 계산. 플랫폼이 글마다 주소를 저장해 내려주므로 사이트는 주소 규칙을
+알 필요가 없습니다 — 권장 형태는 `path: post.path ?? "/blog/" + post.slug` 처럼
+**원장을 먼저 읽고 이 라우트의 기본 주소로만 폴백**하는 것입니다(구 서버·주소 규칙이
+없는 유형이면 `post.path` 가 없거나 `null`). `storedPostPath(post)` 헬퍼
+(`@roottale/cms-renderer-next/routes`)는 소속(모델·컬렉션)이 있는 글의 저장 경로만
+돌려주고, 어느 유형에도 속하지 않는 레거시 글의 `/blog` 폴백값은 무시합니다.
+
 ### 공지·블로그 다중 스트림 (ADR-0060)
 
 섹션을 나눈 사이트(공지 `/notice` + 블로그 `/blog`)는 `path` 를 직접 쓰지 말고
@@ -500,6 +562,10 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
 canonical 을 생략합니다(섹션 없는 글은 상세·sitemap에서 제외되는 규칙과 동일).
 단일 블로그 사이트는 기존처럼 `path: "/blog/" + post.slug` 만 주면 됩니다.
 
+원본 post 를 그대로 넘기면 `post.path`(플랫폼 저장 경로)가 `collections` 계산보다
+먼저 canonical 이 됩니다 — 컬렉션 규칙이 바뀌어도 사이트 코드를 고칠 필요가 없고,
+`collections` 는 저장 경로가 없는 글(구 서버·주소 규칙 없는 유형)의 폴백으로만 쓰입니다.
+
 ### 다국어 hreflang (ADR-0052 A안, W4-6 PR C1)
 
 번역 사이트는 `translations`(글 응답의 `translations[]`)와 `locales` 옵션을

package/docs/theme-and-settings.md

@@ -126,6 +126,9 @@ const settings = await fetchBlogSettings({
 });
 // showTableOfContents, showAuthor, showDate, showAuthorCard,
 // tocTitle, authorProfileImageRadius / Position 등
+// siteProfile: siteDescription · homeTitle · homeDescription(메인 홈 전용
+// 검색 제목·설명, null 이면 사이트 이름·사이트 설명으로 폴백) · logoUrl ·
+// faviconUrl · defaultOgImageUrl — 사이트 <head>/OG 폴백 (seo.md 참고)
 
 // 글 단위 오버라이드(metaJson)와 합성해 최종 표시값 계산
 const display = resolvePostDisplay(settings, post);

package/examples/nextjs/app/blog/[slug]/page.tsx

@@ -37,7 +37,8 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
       section: post.category || undefined,
       tags: post.tags.map((t) => t.name),
     },
-    { siteUrl: SITE_URL, path: `/blog/${post.slug}` },
+    // ADR-0105 — 주소는 플랫폼 원장(post.path)을 읽고, 없을 때만 이 라우트 기본값.
+    { siteUrl: SITE_URL, path: post.path ?? `/blog/${post.slug}` },
   );
 }
 
@@ -49,7 +50,8 @@ export default async function PostPage({ params }: Props) {
   const redirect = postRedirectPath(post, slug);
   if (redirect) permanentRedirect(redirect);
 
-  const url = `${SITE_URL}/blog/${post.slug}`;
+  // ADR-0105 — 정본 주소는 플랫폼 원장(post.path). 없을 때만 이 라우트 기본값.
+  const url = `${SITE_URL}${post.path ?? `/blog/${post.slug}`}`;
   // avcd 구조 — BlogPosting + 확장 옵션(전부 선택, 있는 값만 채우면 됩니다).
   const jsonLd = articleSchema({
     type: "BlogPosting",

package/examples/nextjs/app/blog/categories/[slug]/page.tsx

@@ -80,7 +80,7 @@ export default async function CategoryArchivePage({ params }: Props) {
       <ul>
         {posts.map((post) => (
           <li key={post.id}>
-            <Link href={`/blog/${post.slug}`}>{post.title}</Link>
+            <Link href={post.path ?? `/blog/${post.slug}`}>{post.title}</Link>
           </li>
         ))}
       </ul>

package/examples/nextjs/app/blog/page.tsx

@@ -18,7 +18,7 @@ export default async function BlogPage() {
       <ul>
         {posts.map((post) => (
           <li key={post.id}>
-            <Link href={`/blog/${post.slug}`}>
+            <Link href={post.path ?? `/blog/${post.slug}`}>
               {post.category && <span>{post.category}</span>}
               <h2>{post.title}</h2>
               <p>{post.description}</p>