@roottale/cms-mcp 0.68.0 → 0.70.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @roottale/cms-mcp
 
+## 0.70.0
+
+### Minor Changes
+
+- 49145e4: 콘텐츠 공개·색인 정책의 기존 단일 when 조건을 유지하면서, 공개 필드가 모두 일치하는 all과 모두 일치할 때만 검사를 제외하는 unlessAll을 추가합니다. 각 그룹은 equality 조건 1~4개만 허용하고 중첩하지 않으며, 기존 공개 필드 참조·검사 개수 한도에 포함합니다.
+
+  명시적인 방송 기록 조건이 모두 충족된 경우에만 검수·출연자 조건의 예외를 적용하고, 출처 필수와 강제 검색 제외를 함께 선언하는 공개 예제를 제공합니다. 누락 값과 null은 false로 바꾸지 않으며 관리자 projection·웹훅·FRONT가 같은 정책을 사용합니다.
+
+  글의 공개 영상 필드를 `videoThumbnail: { source: "youtube", field, when? }`로 연결합니다. 선언한 모델에만 안전한 대표 이미지 다음으로 정확한 YouTube ID의 썸네일을 사용하며, 수동 SEO와 기존 무옵션 모델의 이미지 의미는 유지합니다. 같은 공개 필드와 조건을 관리자 자동값·버전·검증과 FRONT 카드/메타데이터에 재사용할 수 있습니다.
+
+## 0.69.0
+
+### Minor Changes
+
+- 30b830f: 분류 기반 경로에서 선언한 첫 분류 선택, 미분류 대체 경로와 예약 경로를 공통 계산기로 처리합니다. 기존 분류 하나 필수 규칙은 그대로 유지합니다.
+
+  공개 필드와 본문에 기반한 콘텐츠 공개·검색 색인 정책 및 목록 선택 계약을 추가합니다. FRONT의 본문, 목록, sitemap과 관리자 메타데이터가 같은 평가기를 사용하며 강제 검색 제외 사유와 정책 전용 웹훅 캐시 무효화를 제공합니다. 정책을 선언하지 않은 연동의 동작은 유지됩니다.
+
+  글 조회에 캐시 태그 옵션을 공개하고 RootTaleBlogPost에 독립 categoryHref 속성을 추가해 별도 breadcrumb가 있는 사이트도 분류 링크를 정확히 연결할 수 있습니다. 정책 적용 예제와 공개 문서를 함께 제공합니다.
+
+### Patch Changes
+
+- ca5ef33: 공개 분류 API의 주소를 활성 모델 presentation과 같은 분류 계층에서 계산합니다. 레거시 null/blog 분류 범위는 보존하고, 모델이 없는 분류만 기존 컬렉션 설정을 사용합니다. 모델 기반 분류 경로와 완전한 분류 조회를 소비하는 공개 예제를 보완합니다.
+
 ## 0.68.0
 
 ### Minor Changes

package/dist/index.js

@@ -1855,7 +1855,7 @@ function registerTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.68.0" : "dev";
+var VERSION = true ? "0.70.0" : "dev";
 var SERVER_INSTRUCTIONS = `
 roottale-cms-mcp\uB294 RootTale CMS\uB97C \uC678\uBD80 \uC0AC\uC774\uD2B8(\uC8FC\uB85C Next.js)\uC5D0 \uC5F0\uB3D9\uD558\uACE0
 \uAE00\xB7\uC378\uB124\uC77C\xB7\uBCF8\uBB38 \uC774\uBBF8\uC9C0\uB97C \uC790\uB3D9\uD654\uD558\uAE30 \uC704\uD55C \uBB38\uC11C\xB7\uC608\uC2DC \uCF54\uB4DC\xB7API tool\uC744 \uC81C\uACF5\uD569\uB2C8\uB2E4.

package/docs/blog.md

@@ -159,6 +159,21 @@ export default async function PostPage({
 카테고리가 있으면 H1 위에 링크로 표시됩니다. 메타 줄에는 발행일이 명시되고,
 수정일의 달력 날짜가 발행일과 다를 때만 수정일을 따로 표시합니다.
 
+SDK 0.69.0부터 `categoryHref`로 H1 위 카테고리 링크를 별도로 지정할 수 있습니다.
+`breadcrumb` 없이도 동작하며, 우선순위는 독립 `categoryHref` →
+`breadcrumb.categoryHref` → 기본 `/blog/categories/{slug}`입니다.
+브레드크럼 링크도 바꾸려면 `breadcrumb.categoryHref`에 같은 함수를 전달하세요.
+
+```tsx
+<RootTaleBlogPost
+  apiKey={apiKey}
+  slugOrId={post.id}
+  categoryHref={(slug) => `/insights/${encodeURIComponent(slug)}`}
+/>
+```
+
+위 `/insights/{slug}`는 해당 사이트에 실제로 구현한 분류 허브 주소여야 합니다.
+
 편집자가 어드민 "관련 콘텐츠"에서 글을 골라 두면(유형 무관, 최대 10개) `RootTaleBlogPost` 는
 `relatedPostsCount` 와 무관하게 **그 글들을 고른 순서대로** 글 하단에 그립니다(발행 글만, 저장된
 공개 주소로 링크). 고른 것이 없을 때만 아래 자동 추천이 동작합니다.

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

@@ -105,6 +105,72 @@ FAQ·도움말·문서처럼 목록 아래에 여러 단계의 분류 허브가
 `path`를 그대로 쓰고, 분류 허브 화면에서 하위 분류와 그 분류에 바로 붙은 글을 함께
 보여 주면 됩니다.
 
+### 여러 분류 중 대표 분류 선택
+
+SDK 0.69.0부터 `categorySelection: "first"`로 여러 분류를 붙인 글의 대표 분류를
+선택할 수 있습니다. 생략하면 기존의 한 분류 경로 규칙을 유지합니다.
+`first`는 **`termOrder` 오름차순 → 같은 순서이면 ID 오름차순**으로 고릅니다.
+공개 응답의 `terms` 배열 순서는 바꾸지 않으므로 `terms.find(...)`나 이름 정렬로
+대표 분류를 대신 고르지 마세요. `categoryCardinality: "exactly-one"`과는 함께
+선언할 수 없습니다.
+
+```json
+{
+  "key": "blog",
+  "cardinality": "collection",
+  "preset": "article",
+  "compatibilityCollectionKey": null,
+  "presentation": {
+    "kind": "category_tree",
+    "basePath": "/insights",
+    "categoryDepth": 1,
+    "categorySelection": "first",
+    "categoryCardinality": "multiple",
+    "categoryFallbackSlug": "general",
+    "reservedCategorySlugs": ["notices"],
+    "categoryPath": "direct",
+    "templateKey": "blog"
+  }
+}
+```
+
+이 예에서 분류를 하나도 붙이지 않은 글은 `/insights/general/{slug}`를 사용합니다.
+`categoryFallbackSlug`는 `first`인 1단계 모델에서만 지원하며, 실제 분류가 없을
+때의 경로입니다. 잘못되거나 다른 모델에 속한 분류 참조를 대체하지 않습니다.
+`general`이라는 분류나 메타데이터 고정 경로를 만들 필요가 없습니다.
+fallback slug와 `reservedCategorySlugs`는 실제 분류 slug로 쓸 수 없고 서로 겹칠
+수도 없습니다. 예약 주소의 페이지는 사이트가 별도로 구현합니다.
+
+`compatibilityCollectionKey: null`은 레거시 컬렉션에 연결하지 않겠다는 명시값입니다.
+모델 key로 바꾸지 마세요. 글 조회에는 `modelKey: "blog"`를 사용하고, 링크에는
+공개 응답의 `post.path`를 사용합니다.
+
+분류 주소도 `fetchCategoryCounts()`의 `category.path`를 사용합니다. 서버는 활성
+모델의 presentation과 해당 모델의 분류 계층으로 주소를 계산합니다. 모델이 없는
+분류만 이전 `content_collections` 설정으로 계산하며, 예약 주소나 잘못된 계층의
+`path: null`을 임의 URL로 대체하지 않습니다. 발행 글이 0건인 실제 분류도 응답에
+포함되며 화면 공개·검색 색인 여부는 사이트의 동일한 정책으로 판단합니다.
+
+분류 응답의 `collectionKey`는 원본 값을 보존합니다. 서버의 모델 선택은 정확한
+모델 key를 우선하며 호환 컬렉션 key도 지원합니다. 위처럼 호환 key가 `null`인
+`blog` 모델의 분류 범위에는 레거시 `null`과 `"blog"`가 모두 들어갑니다.
+이 예시에서는 `(category.collectionKey ?? "blog") === "blog"`로 범위를 선택합니다.
+이 범위와 `category.path`를 canonical·sitemap에서 함께 사용하고, `truncated: true`인
+응답을 완전한 분류 계층으로 간주하지 마세요. 실행 예제는
+`lib/content-policy.ts`의 `fetchBlogCategoryGraph`를 참고하세요.
+
+분류 표시·브레드크럼에도 같은 선택이 필요하면 공개 core 헬퍼를 사용합니다.
+`modelCategories`에는 글에 붙은 분류만이 아닌 **해당 모델의 전체 분류**를 전달합니다.
+
+```ts
+import { resolveCategoryTreeEntryCategory } from "@roottale/cms-core";
+
+const selected = resolveCategoryTreeEntryCategory(presentation, post, modelCategories);
+// selected.kind === "category": selected.category와 selected.chain 사용
+// selected.kind === "fallback": selected.slug 사용(실제 분류 ID는 없음)
+// selected === null: 유효한 분류 경로가 없음
+```
+
 ### 목록·피드 규칙도 모델이 소유합니다
 
 글 목록의 카테고리 모음, RSS 피드, 허브 주소 형식처럼 예전 `collections`

package/docs/getting-started.md

@@ -103,6 +103,14 @@ pnpm add @roottale/cms-client @roottale/cms-renderer-next
 
 요구사항: Node ≥ 18.18, React 19, Next.js 14+ (renderer-next 사용 시).
 
+분류 선택·공개 콘텐츠 정책 API는 SDK **0.69.0부터** 제공합니다. 이 API를 직접
+사용하는 사이트는 `@roottale/cms-core`도 직접 의존성으로 설치하고 세 패키지의
+버전을 맞추세요.
+
+```bash
+pnpm add @roottale/cms-client@0.69.0 @roottale/cms-renderer-next@0.69.0 @roottale/cms-core@0.69.0
+```
+
 렌더러 스타일은 root layout에서 1회 import:
 
 ```ts

package/docs/revalidation-webhooks.md

@@ -122,6 +122,50 @@ const menu = await fetchMenu({ apiKey, slug: "primary", tags: [MENUS_CACHE_TAG]
 > 어드민에도 오류가 안 뜨기 때문에, 이 누락은 "가끔 늦게 반영된다"로만 보입니다.
 > 응답 본문의 `revalidated.requestedTags`가 빈 배열이면 주입이 빠진 것입니다.
 
+### 공개 정책에 사용하는 데이터 갱신
+
+SDK 0.69.0부터 공개 콘텐츠 정책을 쓰는 사이트는 수신 라우트에
+`contentPolicies`를 명시합니다. 값은 **실제 배포 계약의
+`metadata.posts.contentPolicies`**이며 상세·목록·사이트맵이 사용하는 정책과
+같아야 합니다. 이 옵션을 주면 빈 객체여도 `revalidateTag`가 필수입니다.
+누락하면 팩토리 생성 시 오류가 납니다.
+
+```ts
+import { registeredContentPolicies } from "@/lib/content-policy";
+
+export const POST = createRevalidateRoute({
+  apiKey: process.env.ROOTTALE_API_KEY!,
+  revalidate: revalidatePath,
+  revalidateTag: (tag) => revalidateTag(tag, { expire: 0 }),
+  contentPolicies: registeredContentPolicies,
+});
+```
+
+Next.js 예제의 `registeredContentPolicies`는 미등록 상태인 `undefined`입니다.
+실제 사이트 계약에서 가져온 값으로 바꾸고 정책을 모든 소비 화면에 연결하면
+활성화됩니다. 정책을 선언하지 않은 기존 연동의 태그 동작은 유지됩니다.
+
+정책 평가에 사용하는 글·전체 목록·분류·모델·컬렉션 조회에는
+`CONTENT_POLICY_CACHE_TAG`를 붙입니다. `fetchPost`·`fetchPosts`도 `tags`를
+지원합니다. 이미 쓰는 태그가 있다면 덮어쓰지 말고 함께 전달하세요.
+
+```ts
+import { CONTENT_POLICY_CACHE_TAG, fetchPosts } from "@roottale/cms-client/server";
+
+const firstPage = await fetchPosts({
+  apiKey, modelKey: "blog", limit: 100,
+  tags: [CONTENT_POLICY_CACHE_TAG],
+});
+// 정책 쿼리는 firstPage에서 끝내지 않고 hasMore/nextCursor로 끝까지 수집합니다.
+```
+
+정책 옵션이 있으면 서명이 검증된 `post.*`·`media.*`·`metadata.updated` 이벤트에서
+`CONTENT_POLICY_CACHE_TAG`와 `METADATA_CACHE_TAG`를 자동으로 무효화합니다.
+`theme.updated`·`taxonomy.updated`에서는 기존 설정 태그와 공개 정책 태그를 지우고
+루트 layout을 갱신합니다. 관련 경로를 계산하기 전에 조회 캐시를 갱신하므로 변경된
+현재 값으로 공개·색인 여부를 다시 평가할 수 있습니다. `fetchRouteMetadata`의
+메타데이터 태그는 자동 부착되며 소비자가 같은 무효화를 중복 구현할 필요가 없습니다.
+
 ## 2. 어드민에서 알림 보낼 주소 확인
 
 웹훅 주소는 따로 적지 않습니다. 어드민 **설정 > 사이트 정보**의 **공개 도메인**과

package/docs/seo.md

@@ -69,6 +69,24 @@ export async function generateMetadata() {
 
 공유 이미지 자동값은 대표 이미지 → 선언한 본문 첫 이미지·이전 이미지 순입니다. `useFeaturedImage: false` 또는 분류의 `useTermImage: false`로 기존 화면에서 사용하지 않던 콘텐츠 이미지를 제외할 수 있습니다. `defaultRules.defaults`는 콘텐츠 값이 없을 때 사용할 코드 기본값으로, 사이트 공통값보다 먼저 적용됩니다. 글에 고정 공유 이미지를 쓰려면 `useFeaturedImage: false`와 `defaults.ogImage`를 함께 선언하고 본문·이전 이미지 규칙은 켜지 않습니다. `defaultRules.fallback`은 사이트 공통값 뒤에 적용됩니다.
 
+SDK 0.70.0부터 글의 공개 영상 필드를 이미지 자동값으로 연결할 수 있습니다.
+`videoThumbnail: { source: "youtube", field: "video_url", when: { field: "content_format", equals: "media" } }`를
+등록하고 FRONT에도 같은 규칙과 `fields: post.fields`를 전달합니다. 이 옵션을 선언한
+모델은 안전한 절대 HTTPS 대표 이미지 → 조건에 맞는 YouTube 썸네일 → 기존
+본문·이전 이미지 → 코드·사이트 기본값 순으로 계산합니다. 대표 이미지가 HTTP·상대
+주소·인증정보 포함 URL이면 영상 후보를 사용하며, 수동 SEO 이미지에는 이 변환을
+적용하지 않습니다. 옵션 없는 모델의 기존 이미지 처리는 유지됩니다.
+
+YouTube 입력은 인증정보·공백·제어문자·역슬래시 없는 HTTPS URL만 받습니다.
+`youtu.be/<id>` 또는 `youtube.com`·`www.youtube.com`·`m.youtube.com`의
+`watch?v=<id>`·`shorts/<id>`·`embed/<id>`에서 영문·숫자·`_`·`-`로 된 11자 ID만
+읽고 `https://i.ytimg.com/vi/<id>/hqdefault.jpg`를 만듭니다. 시작 시각은 이미지에
+영향을 주지 않습니다. 임의 호스트·이미지 URL 형식은 선언할 수 없습니다.
+카드에서도 같은 자동 썸네일이 필요하면 core의
+`metadataVideoThumbnail(rule.videoThumbnail, post.fields)`를 사용합니다.
+영상·조건·같이 선언한 텍스트 토큰은 공개 필드 투영을 사용하며 비공개 필드나
+원본 ACF를 넘기지 않습니다. 글 자동값 전용 옵션이며 분류에는 선언하지 않습니다.
+
 검색 차단을 유지해야 하는 동적 모델은 `defaultRules[modelKey].robots: { forceNoindex: true, forceNofollow: true }`를 선언하고 같은 `robots`를 `resolveMetadata`나 페이지 빌더에 전달합니다. 직접 입력한 `false`로 이 제한을 해제할 수 없습니다. 기존 모델 소속과 실제 FRONT 분류 경로가 다른 경우 `metadata.terms.archivePaths: { notice: "/blog/:slug" }`처럼 등록 모델별 내부 경로를 선언합니다. 이 값은 메타데이터 조회·편집·재검증 주소만 맞추며 공개 라우트나 콘텐츠 소속을 변경하지 않습니다. 마지막 `:slug` 하나만 지원합니다.
 
 `fetchCategoryCounts`는 API의 `category_index_activated`를 `categoryIndexActivated`로 보존합니다. 색인 전환을 요구하는 계약에서는 이 값이 `true`일 때만 `hubPromoted` 기반 정책을 적용하고 이전 정책은 그때까지 유지합니다. 분류 메타데이터 조회에도 `tags: [METADATA_CACHE_TAG]`를 전달할 수 있습니다.
@@ -77,6 +95,152 @@ export async function generateMetadata() {
 
 사이트맵도 같은 최종 `noindex`·대표 경로 정책을 사용하고 활성 리다이렉트 출발 주소를 제외해야 합니다. 목록의 페이지 번호·필터별 정책은 사이트 라우트에서 계산합니다. 메타데이터 저장 성공·웹훅 수신 성공·실제 HTML 반영 확인은 서로 다른 상태입니다.
 
+### 동적 콘텐츠의 공개·색인 정책
+
+SDK 0.69.0의 `ContentPolicy`·`ContentQuery`는 `@roottale/cms-core`에서 제공합니다.
+배포 계약의 `metadata.posts.contentPolicies[modelKey]`와 FRONT가 같은 선언을
+사용하면, 현재 공개 필드·본문·경로를 기준으로 글과 목록을 다시 평가합니다.
+`visibility`를 통과한 글만 화면에 표시하고, `indexing`까지 통과한 글만 검색에
+허용합니다. 결과의 `visible`과 `indexable`은 별개이며 `robots`를 메타데이터
+빌더에 전달해야 직접 설정한 `noindex: false`가 강제 제한을 풀지 못합니다.
+
+```ts
+import type { ContentPolicy, ContentQuery } from "@roottale/cms-core";
+
+// 아래 필드는 활성 공개 필드 그룹에 선언되어 있어야 합니다.
+export const contentPolicies = {
+  blog: {
+    visibility: [
+      { field: "active", op: "notEquals", value: false },
+      { field: "content_format", op: "oneOf", values: ["article"], allowEmpty: true },
+      { op: "bodyContent", allowExcerpt: true },
+    ],
+    indexing: [
+      { op: "bodyText" },
+      { field: "reviewer_name", op: "text" },
+      { field: "reviewed_at", op: "date" },
+      { field: "sources", op: "some", checks: [
+        { field: "label", op: "text" },
+        { field: "url", op: "safeHttps" },
+      ] },
+    ],
+  },
+} satisfies Record<string, ContentPolicy>;
+
+export const blogQuery = {
+  modelKeys: ["blog"], pinnedField: "pinned", pageSize: 12,
+} satisfies ContentQuery;
+```
+
+등록 위치는 글 정책이 `metadata.posts.contentPolicies`, 고정 목록이
+`metadata.routes[].contentQuery`, 분류별 목록이 `metadata.terms.contentQueries[modelKey]`입니다.
+쿼리가 참조하는 모든 모델에는 글 정책이 있어야 하며, 선언한 `posts.modelKeys`와
+`terms.modelKeys`의 범위를 지킵니다. 본문 페이지(`source.kind: "page"`)에는
+목록 쿼리를 붙이지 않습니다. 기존 정책·쿼리 없는 계약의 동작은 유지됩니다.
+
+필드 검사는 `equals`·`notEquals`·`oneOf`·`text`·`date`·`safeHttps`·`allowedPath`와
+한 단계 repeater의 `some`만 지원합니다. `when: { field, equals }`로 특정 값일 때만
+검사할 수 있습니다. SDK 0.70.0부터는 `when: { all: [...], unlessAll: [...] }`도
+지원합니다. `all`은 조건이 모두 일치해야 하고, `unlessAll`은 조건이 모두 일치할
+때만 검사를 생략합니다. 두 그룹 중 하나 이상을 선언하며 각 그룹은 equality 조건
+1~4개만 받습니다. 빈 그룹·중첩·단일 조건과 그룹의 혼합은 허용하지 않습니다.
+조건의 필드도 공개 필드 64개 한도에 포함합니다. `visibility`·`indexing` 각각의
+검사 24개 한도는 그대로입니다. `all`과 `unlessAll`을 함께 쓰면 두 제한을 모두
+충족해야 합니다. 누락·`null`은 명시적인 `false`와 같지 않습니다.
+임의 함수·정규식·중첩 repeater·관계형 값은 정책 입력이 아닙니다.
+`post.fields`의 공개 값만 사용하고 비공개 ACF를 전달하지 마세요. 누락 값은
+`undefined`이며 `notEquals: false`는 누락도 통과합니다. `oneOf`의
+`allowEmpty: true`는 누락·`null`·빈 문자열·`false`·`0`도 허용하므로 필수 필드에는
+해당 옵션을 사용하지 않습니다.
+
+예를 들어 방송 기록을 `content_format === "media"`·`broadcast_record === true`·
+`medical_content === false`인 경우로 한정한다면, 다음 조건들을 **같은 전체 정책**의
+검수·출연자·출처 검사에 연결합니다. 예외일 때만 일부 검사를 생략하고, 출처 필수와
+강제 검색 제외는 유지합니다. 이 조건 선언만으로 글을 공개하지는 않습니다.
+
+```ts
+// 실행 예제 lib/content-policy.ts가 같은 조건을 제공합니다.
+const record = [
+  { field: "content_format", equals: "media" },
+  { field: "broadcast_record", equals: true },
+  { field: "medical_content", equals: false },
+];
+const reviewWhen = { unlessAll: record };
+const performerWhen = {
+  all: [{ field: "content_format", equals: "media" }], unlessAll: record,
+};
+const recordSourcesWhen = { all: record };
+// indexing에 추가하면 예외 방송 기록은 수동 noindex:false로 풀 수 없습니다.
+const recordNoindexCheck = {
+  field: "broadcast_record", op: "notEquals", value: true,
+  when: { all: [
+    { field: "content_format", equals: "media" },
+    { field: "medical_content", equals: false },
+  ] },
+};
+```
+
+`bodyContent`는 표시 가능한 HTML 또는 JSON 텍스트를 확인하고, 명시한 경우에만
+요약·대표 이미지·`additionalUrl`을 대체 콘텐츠로 허용합니다. `bodyText`는 사용할
+HTML이 있으면 그 텍스트를, 없으면 JSON의 `text` 노드를 읽습니다. 이미지뿐인
+본문은 텍스트 검사를 통과하지 않습니다. 본문 소스 선택은 core의
+`resolvePostBodySource`로 공유하며 기존 renderer/server의 같은 export도 유지됩니다.
+
+`evaluateContentPolicy`를 직접 부를 때는 **`expectedPath`에
+`resolvePostPublicPath(post, modelContext)` 결과를 반드시 전달**합니다. `null`도
+그대로 전달하며 `post.path` 자체를 넣지 않습니다. `modelContext`에는 현재 모델의
+presentation·호환 컬렉션·전체 분류가 필요합니다. 발행 상태·발행일·대표 경로와
+모델 경로가 맞는지도 평가하므로, 임의로 만든 경로로 잘못된 글을 통과시키지 않습니다.
+
+실행 예제 `examples/nextjs/lib/content-policy.ts`는 모든 커서를 수집하고 같은
+평가 결과를 재사용합니다. 다음 코드의 `contextFor`에는 위 모델 정보를 돌려주는
+사이트 함수를 전달합니다.
+
+```ts
+import { evaluateContentQuery, type PublicPathContext } from "@roottale/cms-core";
+import { fetchAllContentPolicyPosts, evaluateContentPolicyPosts,
+  type PolicyPost } from "@/lib/content-policy";
+// 위 contentPolicies와 blogQuery를 같은 사이트 모듈에서 가져옵니다.
+
+async function loadBlogPage(
+  apiKey: string,
+  page: number,
+  contextFor: (post: PolicyPost) => PublicPathContext,
+) {
+  const posts = (await Promise.all(blogQuery.modelKeys.map((modelKey) =>
+    fetchAllContentPolicyPosts({ apiKey, modelKey, locale: "ko" }),
+  ))).flat();
+  const candidates = evaluateContentPolicyPosts(posts, contentPolicies, contextFor);
+  const listing = evaluateContentQuery(blogQuery, candidates, { complete: true, page });
+  return { listing, candidates };
+}
+```
+
+첫 100건만 읽은 결과에 `complete: true`를 붙이지 마세요. 모든 모델의 마지막
+커서까지 성공한 뒤에만 완전한 입력입니다. `complete: false`는 예외이며 네트워크
+실패·커서 누락도 빈 목록이나 `noindex` 성공으로 바꾸지 않습니다.
+
+쿼리는 공개 가능한 글 → 모델·필터·범위 선택 → `pinnedField === true` 우선 →
+발행일 내림차순·ID 오름차순 → 현재 페이지 순으로 계산합니다. 목록의 색인 여부는
+**현재 페이지 안에** 색인 가능한 글이 있는지로 정합니다. 본문은 `listing.items`,
+메타데이터는 같은 `listing.robots`를 사용하세요. `filters`는
+`equals`·`notEquals`·`oneOf`, `scope`는 `currentTerm`(분류 ID 필수) 또는
+`currentPath`(현재 목록 경로 필수)만 지원합니다. 여러 목록을 평가할 때에는 필요한
+모델의 합집합을 한 번 수집하고 `candidates`를 재사용할 수 있습니다.
+
+빈 분류가 실제로 404인 사이트만 분류 쿼리에 `requireItems: true`를 선언합니다.
+일반 목록의 빈 첫 페이지는 `visible: true`, `indexable: false`이므로 200 화면을
+유지합니다. 범위를 벗어난 페이지는 `visible: false`입니다. 고정 목록에는
+`requireItems: true`와 `scope: "currentTerm"`을 선언할 수 없습니다. 관리자 목록
+메타데이터와 사이트맵은 첫 페이지, FRONT는 요청받은 페이지 번호로 평가합니다.
+
+사이트맵도 `candidates`의 글 정책과 같은 목록 쿼리를 사용하고 최종 수동 SEO·강제
+robots·canonical·리다이렉트 제외 규칙을 함께 적용합니다. 기존 `createSitemapIndex`
+팩토리가 등록 정책을 자동으로 가져오지는 않으므로 정책을 쓰는 사이트의 사이트맵
+수집 코드에도 연결하세요. `selectContentQuery`는 글 정책과 목록 평가를 한 번에
+호출하는 편의 API이며, 여러 화면에서 재사용할 때는 위처럼 두 평가를 분리합니다.
+캐시 연결은 [발행 웹훅 문서](revalidation-webhooks.md)의 공개 정책 절을 따릅니다.
+
 ### 관리 API·MCP
 
 CLI도 같은 관리 API를 사용합니다. `rt cms metadata list --site-id <site-id> --kind route --state custom`, `rt cms metadata get route home --site-id <site-id>`로 조회합니다. 수정은 `rt cms metadata update route home --site-id <site-id> --input-file patch.json`이며 파일에는 `{ "expected_version": "직전 조회값", "patch": { "title": null } }`처럼 실제 변경만 넣습니다. 인증키를 명령 인자에 넣지 마세요.

package/examples/nextjs/app/api/revalidate/route.ts

@@ -7,6 +7,7 @@
 import { revalidatePath, revalidateTag } from "next/cache";
 import { THEME_CACHE_TAG } from "@roottale/cms-client/server";
 import { createRevalidateRoute } from "@roottale/cms-renderer-next/routes";
+import { registeredContentPolicies } from "@/lib/content-policy";
 
 // 2번째 인자(type)를 반드시 그대로 넘긴다 — 팩토리가 설정 저장 시
 // `revalidate("/", "layout")` 을 부르는데, 콜백이 path 만 받으면 "layout" 이
@@ -34,6 +35,9 @@ export const POST = createRevalidateRoute({
   // 받는다("max" 의 expire 는 1년이다). `updateTag` 는 Server Action 전용이라
   // route handler 에서 throw 하므로 쓰지 않는다.
   revalidateTag: (tag: string) => revalidateTag(tag, { expire: 0 }),
+  // 정책을 쓰는 사이트는 배포 계약 metadata.posts.contentPolicies를 연결합니다.
+  // 예제의 undefined는 opt-in 전 상태입니다. 설정하면 revalidateTag가 필수입니다.
+  contentPolicies: registeredContentPolicies,
   themeTag: THEME_CACHE_TAG,
   // 사이트맵 인덱스 + 분리된 하위 사이트맵(static/blog/categories)을 모두 무효화.
   // 홈에 최신 글 섹션이 있으면 "/" 포함 — 글 변경 시 홈도 함께 갱신.

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

@@ -89,6 +89,8 @@ export default async function PostPage({ params }: Props) {
         theme={null}
         footerPatternPresentation={null}
         relatedPostsCount={3}
+        // H1 위 카테고리 링크. breadcrumb 없이도 독립적으로 사용할 수 있습니다.
+        categoryHref={(category) => `/blog/categories/${encodeURIComponent(category)}`}
         // opt-in — 시각 브레드크럼 + BreadcrumbList JSON-LD. siteUrl 없으면
         // 시각 브레드크럼만(JSON-LD 미emit).
         breadcrumb={{ siteUrl: SITE_URL }}

package/examples/nextjs/lib/content-metadata.ts

@@ -7,6 +7,7 @@ import {
   type MetadataDefaultsDeclaration,
   type MetadataValues,
 } from "@roottale/cms-client/server";
+import { contentPolicySafeHttpsUrl, metadataVideoThumbnail } from "@roottale/cms-core";
 
 /** Register this same declaration in the deployed site's metadata.posts contract. */
 export const contentMetadataDefaults: MetadataDefaultsDeclaration = {
@@ -20,6 +21,7 @@ export const contentMetadataDefaults: MetadataDefaultsDeclaration = {
         defaults: { ogImage: "/images/logo.png", ogImageAlt: "사무소 로고" },
       },
       blog: {
+        videoThumbnail: { source: "youtube", field: "video_url", when: { field: "content_format", equals: "media" } },
         description: {
           normalizeWhitespace: true, maxLength: 160, lengthUnit: "code-points", ellipsis: "…",
           bodyFallback: {}, fallback: "%s에 관한 안내입니다.",
@@ -29,6 +31,13 @@ export const contentMetadataDefaults: MetadataDefaultsDeclaration = {
   },
 };
 
+/** Card image uses the same declared public field; it does not copy site SEO defaults. */
+export function contentCardImage(post: CmsPostContent): string | undefined {
+  const modelKey = post.modelKey ?? post.collectionKey ?? "blog";
+  const rule = contentMetadataDefaults.posts?.defaultRules?.[modelKey];
+  return contentPolicySafeHttpsUrl(post.featuredImageUrl) ?? metadataVideoThumbnail(rule?.videoThumbnail, post.fields);
+}
+
 /** Metadata cleanup applies to automatic values only. Stored SEO and canonical remain separate. */
 export function contentMetadata(post: CmsPostContent, siteUrl: string, siteDefaults: MetadataValues): MetadataValues {
   const modelKey = post.modelKey ?? post.collectionKey ?? "blog";

package/examples/nextjs/lib/content-models.ts

@@ -4,7 +4,7 @@ const apiKey = process.env.ROOTTALE_API_KEY!;
 
 export async function getTeamMembers() {
   const models = await fetchContentModels({ apiKey });
-  const model = models.models.find((candidate) => candidate.key === "team-member");
+  const model = models.find((candidate) => candidate.key === "team-member");
   if (!model || model.preset !== "entity") return [];
 
   const response = await fetchPosts({ apiKey, modelKey: model.key, limit: 100 });

package/examples/nextjs/lib/content-policy.ts

@@ -0,0 +1,118 @@
+// @roottale/cms-core를 사이트의 직접 의존성에 추가합니다(SDK 0.70.0+).
+import {
+  ContentPolicyWhenSchema,
+  evaluateContentPolicy,
+  resolvePostPublicPath,
+  type ContentPolicy,
+  type ContentPolicyCheck,
+  type ContentQueryCandidate,
+  type MetadataRobotsPolicy,
+  type PublicPathContext,
+} from "@roottale/cms-core";
+import {
+  CONTENT_POLICY_CACHE_TAG,
+  fetchCategoryCounts,
+  fetchPosts,
+  type CmsPostContent,
+  type FetchCategoryCountsOptions,
+  type FetchPostsOptions,
+} from "@roottale/cms-client/server";
+
+// 이 예제에는 등록된 사이트 콘텐츠 계약이 없습니다. 정책을 사용하는 사이트는
+// 배포 계약 metadata.posts.contentPolicies를 여기서 import하여 그대로 내보냅니다.
+// 상세·목록·사이트맵에 같은 정책을 연결한 뒤 이 값을 설정하세요.
+export const registeredContentPolicies:
+  | Readonly<Record<string, ContentPolicy>>
+  | undefined = undefined;
+
+export type PolicyPost = CmsPostContent & { path: string | null };
+
+// 예외 조건도 등록한 정책 안에 둡니다. 이 상수만으로 글을 공개하지 않습니다.
+// 아래 세 값이 정확히 일치할 때만 방송 기록이며 누락/null은 false가 아닙니다.
+const broadcastRecordFields = [
+  { field: "content_format", equals: "media" },
+  { field: "broadcast_record", equals: true },
+  { field: "medical_content", equals: false },
+];
+export const broadcastRecordWhen = ContentPolicyWhenSchema.parse({ all: broadcastRecordFields });
+export const reviewExceptBroadcastRecordWhen = ContentPolicyWhenSchema.parse({ unlessAll: broadcastRecordFields });
+export const performerExceptBroadcastRecordWhen = ContentPolicyWhenSchema.parse({
+  all: [{ field: "content_format", equals: "media" }],
+  unlessAll: broadcastRecordFields,
+});
+
+/** Add to the full indexing policy; direct noindex:false cannot override a failed check. */
+export const broadcastRecordNoindexCheck: ContentPolicyCheck = {
+  field: "broadcast_record", op: "notEquals", value: true,
+  when: { all: [
+    { field: "content_format", equals: "media" },
+    { field: "medical_content", equals: false },
+  ] },
+};
+
+// 문서의 compatibilityCollectionKey: null인 blog 모델 예제입니다.
+// 경로 계산에는 글에 붙은 분류만이 아닌 모델의 전체 graph가 필요합니다.
+// null collectionKey는 기존 blog 범위이며 응답 원본은 재작성하지 않습니다.
+export async function fetchBlogCategoryGraph(
+  options: Omit<FetchCategoryCountsOptions, "collectionKey" | "excludeCollections">,
+) {
+  const result = await fetchCategoryCounts({
+    ...options, tags: [...new Set([...(options.tags ?? []), CONTENT_POLICY_CACHE_TAG])],
+  });
+  if (result.truncated) throw new Error("모델의 전체 분류를 가져오지 못했습니다");
+  return result.categories.filter((category) => (category.collectionKey ?? "blog") === "blog").map((category) => {
+    if (!category.id) throw new Error("분류의 안정 ID가 없습니다");
+    return { ...category, id: category.id };
+  });
+}
+
+// 첫 100건은 완전한 목록이 아닙니다. query.modelKeys의 각 모델에 대해 호출하고,
+// 모든 호출이 성공한 뒤에만 evaluateContentQuery에 complete: true를 전달합니다.
+export async function fetchAllContentPolicyPosts(
+  options: Omit<FetchPostsOptions, "cursor" | "limit">,
+): Promise<PolicyPost[]> {
+  const posts: PolicyPost[] = [];
+  const cursors = new Set<string>();
+  const tags = [...new Set([...(options.tags ?? []), CONTENT_POLICY_CACHE_TAG])];
+  let cursor: string | undefined;
+  while (true) {
+    const page = await fetchPosts({ ...options, tags, limit: 100, cursor });
+    posts.push(...page.items.map((post) => ({ ...post, path: post.path ?? null })));
+    if (!page.hasMore) return posts;
+    if (!page.nextCursor || cursors.has(page.nextCursor)) {
+      throw new Error("공개 콘텐츠의 다음 커서가 없거나 반복됩니다");
+    }
+    cursors.add(page.nextCursor);
+    cursor = page.nextCursor;
+  }
+}
+
+// 한 요청에서 이 결과를 목록 본문·메타데이터·사이트맵에 재사용합니다.
+// contextFor는 해당 모델의 presentation/호환 컬렉션/전체 분류를 반환해야 합니다.
+// 분류·모델·컬렉션을 fetch할 때도 CONTENT_POLICY_CACHE_TAG를 붙입니다.
+export function evaluateContentPolicyPosts(
+  posts: readonly PolicyPost[],
+  policies: Readonly<Record<string, ContentPolicy>>,
+  contextFor: (post: PolicyPost) => PublicPathContext,
+  options: {
+    now?: number;
+    robotsFor?: (post: PolicyPost) => MetadataRobotsPolicy | undefined;
+  } = {},
+): ContentQueryCandidate<PolicyPost>[] {
+  const now = options.now ?? Date.now();
+  return posts.map((post) => {
+    const modelKey = post.modelKey ?? post.collectionKey ?? "";
+    const policy = Object.hasOwn(policies, modelKey) ? policies[modelKey] : undefined;
+    if (!policy) throw new Error(`모델 ${modelKey}의 공개 정책이 없습니다`);
+    return {
+      post,
+      policy: evaluateContentPolicy(policy, post, {
+        now,
+        // null도 그대로 전달합니다. post.path 자체를 expectedPath로 쓰면
+        // 모델의 실제 경로와 다른 글을 걸러낼 수 없습니다.
+        expectedPath: resolvePostPublicPath(post, contextFor(post)),
+        robots: options.robotsFor?.(post),
+      }),
+    };
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roottale/cms-mcp",
-  "version": "0.68.0",
+  "version": "0.70.0",
   "type": "module",
   "description": "RootTale CMS MCP server and CLI for models, entries, exposures, media, integration docs, and public API access.",
   "bin": {