@roottale/cms-mcp 0.53.0 → 0.53.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @roottale/cms-mcp
 
+## 0.53.1
+
+### Patch Changes
+
+- 6df15b6: 고객 사이트의 서버에서 발행 글과 페이지를 함께 검색할 수 있도록 `searchPosts`에 `type: "all"`과 언어 필터를 추가합니다. 검색 결과에는 콘텐츠 유형과 언어를 포함하고, `resolveSearchHitPath`가 블로그·고정 페이지·콘텐츠 유형·다국어 주소를 안전하게 계산합니다. Next.js 통합 검색 예시와 공개 API 문서도 함께 제공합니다.
+- 1efecbb: 페이지·글·정보의 콘텐츠 모델 공개 계약과 `modelKey` 조회를 추가합니다. 개발자가 선언한 슬롯에서만 배너·팝업을 조회하고 접근성 있게 렌더하는 API, client, renderer, 예제 문서를 함께 제공합니다. 기존 collections와 collectionKey 계약은 유지합니다.
+- a490db2: 사이트 통합 검색의 서버 전용 연동 구조, 실제 콘텐츠 주소 계산, 캐시·장애 처리, 배포 순서와 현재 제약을 설명하는 전용 문서를 추가합니다.
+- 866f4ff: ROOT-ADMIN 필드 그룹을 `collection_key` 기준으로 콘텐츠 유형에 연결하는 방법과 공개 `fields` 연동법을 문서화합니다. 의료 vertical의 `doctors` 유형은 의료진 프로필·반복 이력·진료 시간표·관계 필드를 같은 계약으로 제공합니다.
+- 5cd0e3b: 주소 이동 middleware가 API 장애 시 stale 규칙을 계속 사용하고, 순환 규칙은 브라우저를 왕복시키지 않도록 통과처리합니다. Site Materializer 납품물에 middleware와 회귀 검증 파일을 필수로 포함합니다.
+
 ## 0.53.0
 
 ### Patch Changes

package/dist/index.js

@@ -944,7 +944,7 @@ function registerTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.53.0" : "dev";
+var VERSION = true ? "0.53.1" : "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/api-reference.md

@@ -146,6 +146,9 @@ tenant/site 경로, 크기, 형식을 검증한 뒤 미디어를 등록합니다
 권한으로 발급한 키가 필요합니다** (`settings:write`). 글쓰기 키(`read_write`)로
 호출하면 `403 insufficient_scope` 입니다.
 
+페이지·글·정보 모델과 배너·팝업 슬롯 연동은
+[콘텐츠 모델과 노출 슬롯](./content-models-and-exposures.md)을 참고하세요.
+
 세 가지를 먼저 알아 두세요.
 
 1. **두 엔드포인트 모두 "그 설정 블록 전체 교체"입니다.** 메서드는 `PATCH`
@@ -281,26 +284,31 @@ tenant/site 경로, 크기, 형식을 검증한 뒤 미디어를 등록합니다
 
 ## GET /v1/cms/public/search
 
-발행된 글 키워드 검색 (사이트 내 검색, WP `?s=` 패리티). title·excerpt·본문
-텍스트의 case-insensitive 부분일치, 최신 발행순. 응답은 카드 렌더용 슬림
-hit — 본문(`body_json`)은 미포함이므로 상세는 slug 로 글 1개 API를 호출하세요.
+발행된 콘텐츠 키워드 검색입니다. 제목 완전일치, 제목 부분일치, 요약, 본문
+순으로 관련도를 계산하고 같은 점수에서는 최신 발행순으로 정렬합니다. 응답은
+카드 렌더용 슬림 hit이며 본문(`body_json`)은 포함하지 않습니다.
 
 | 쿼리 | 설명 |
 |---|---|
 | `q` | 검색 키워드 (필수, 1~100자) |
 | `limit` | 결과 수 1~50, 기본 10 |
-| `type` | `post`(기본) \| `page` |
+| `type` | `post`(기본, 하위 호환) \| `page` \| `all`(글+페이지 통합) |
+| `locale` | BCP-47 언어 코드. 생략하면 사이트 기본 언어 |
 | `site_id` | 멀티 사이트 키일 때만 |
 
 ```json
 { "tenant_id": "…", "site_id": "…", "query": "세무",
-  "items": [ { "id": "…", "type": "post", "title": "…", "slug": "…",
+  "items": [ { "id": "…", "type": "post", "collection_key": "notice",
+               "locale": "ko", "title": "…", "slug": "…",
                "excerpt": "…", "featured_media_url": "…",
                "published_at": "…" } ] }
 ```
 
 JS/TS 는 `@roottale/cms-client/server` 의 `searchPosts({ apiKey, query })` 를
-사용하세요 — 구 서버(라우트 미배포)의 404 를 빈 배열로 처리합니다.
+사용하세요. 사이트 전체 검색은 `type: "all"`을 지정합니다. 결과 링크는
+`resolveSearchHitPath(hit, collections, locale?)`로 계산해야 콘텐츠 유형의
+`basePath`와 다국어 경로를 그대로 따릅니다. `ROOTTALE_API_KEY`는 브라우저에
+노출하지 말고 Server Component·Route Handler에서만 사용하세요.
 
 ## GET /v1/cms/public/menus
 
@@ -481,7 +489,7 @@ const { categories, truncated } = await fetchCategoryCounts({
 
 ## GET /v1/cms/public/analytics
 
-분석 태그 설정.
+ROOT-ANALYTICS 사이트 ID와 외부 태그 설정.
 
 ```json
 { "tags": [ { "provider": "ga4", "id": "G-XXXXXXX", "enabled": true } ] }

package/docs/collections.md

@@ -158,6 +158,33 @@ basePath·라벨·플래그는 어드민에서 바꾸면 sitemap·feed·라우
 (블로그면 칼럼·소식 등). 주제는 선택이며, **글 > 분류 > 카테고리**에서 미리 만들어
 콘텐츠 유형에 연결합니다.
 
+### 콘텐츠 유형별 커스텀 필드 (ACF 방식)
+
+**글 > 필드 그룹**에서 콘텐츠 유형마다 별도 입력칸을 만들 수 있습니다. 새 필드
+그룹의 적용 기준을 **콘텐츠 유형**으로 고른 뒤 `doctors`, `reviews` 같은 유형을
+선택하면, 그 유형의 글 편집 화면에만 해당 입력칸이 나타납니다. 카테고리를 임시로
+붙일 필요가 없습니다.
+
+필드 값은 글의 `meta_json.acf`에 저장되며 공개 글 API에서는 정의에 맞게 변환된
+`fields`와 표시용 `fields_meta`로 제공됩니다. 이미지·관계 필드는 raw ID가 아니라
+공개 URL과 안전한 참조 객체로 해석됩니다.
+
+```ts
+const doctors = await fetchPosts({
+  apiKey: process.env.ROOTTALE_API_KEY!,
+  collectionKey: "doctors",
+});
+
+for (const doctor of doctors.items) {
+  // 예: { name, specialty, photo, education, schedule, ... }
+  console.log(doctor.fields);
+}
+```
+
+ROOT-ADMIN의 코드 정의 필드 그룹도 같은 규칙을 씁니다. 의료 vertical의 기본
+`의료진 정보` 그룹은 `doctors` 콘텐츠 유형에 연결되며 이름·전문분야·사진·대체
+텍스트·학력/경력 반복 목록·진료 시간표·담당 치료·검수 책임자를 제공합니다.
+
 ## 사이트 연동 코드
 
 섹션 선언을 route 팩토리에 넘기면 sitemap·feed·revalidate가 거기서 파생됩니다. 두 가지

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

@@ -0,0 +1,63 @@
+---
+title: 콘텐츠 모델과 노출 슬롯
+description: 페이지·글·정보 모델과 배너·팝업을 고객 FRONT에 연결하는 방법
+---
+
+# 콘텐츠 모델과 노출 슬롯
+
+RootTale은 운영 화면의 콘텐츠를 세 가지로 나눕니다.
+
+- 페이지: 개발자가 주소와 화면을 만들고 운영자가 내용을 수정합니다.
+- 글: 운영자가 항목을 만들며 목록·상세 주소가 있습니다.
+- 정보: 인물·서비스·후기처럼 구조화된 값을 운영자가 만들고, 화면은 개발자가 정합니다.
+
+고객 FRONT는 `fetchContentModels()`로 활성 모델을 읽고, `fetchPosts({ modelKey })`로
+특정 모델의 항목만 가져올 수 있습니다. 기존 `fetchCollections()`와
+`collectionKey`는 지원 기간 동안 그대로 동작합니다.
+
+```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,
+});
+```
+
+## 배너·팝업
+
+운영자는 임의 위치에 팝업을 만들 수 없습니다. 개발자가 사이트 콘텐츠 계약에
+등록한 슬롯 안에서만 내용·기간·대상 경로·우선순위를 관리합니다. FRONT는 슬롯을
+코드에 명시하고 `RootTaleExposureSlot`을 놓습니다.
+
+```tsx
+import { RootTaleExposureSlot } from "@roottale/cms-renderer-next/server";
+
+export default async function Layout({ children }: { children: React.ReactNode }) {
+  return <>
+    {children}
+    <RootTaleExposureSlot
+      apiKey={process.env.ROOTTALE_API_KEY!}
+      slotKey="global-popup"
+      path="/"
+      allowedVariants={["card", "image-card"]}
+      revalidate={60}
+    />
+  </>;
+}
+```
+
+알 수 없는 variant, 계약에서 제거된 슬롯, 발행 기간 밖 캠페인은 렌더하지 않습니다.
+팝업은 닫기 버튼과 Escape 닫기를 제공하고 `always|session|day|never` 재노출 정책을
+적용합니다. `@roottale/cms-renderer-next/styles`를 root layout에서 한 번 불러오세요.
+
+## Raw API
+
+- `GET /v1/cms/public/content-models`
+- `GET /v1/cms/public/posts?model_key=people`
+- `GET /v1/cms/public/exposures?slot_key=global-popup&path=%2Fabout`
+
+모두 고객용 API key와 `cms:read` 범위가 필요합니다. 노출 API는 선택된 공개 내용만
+반환하며 초안, 보관함, 내부 일정·타기팅 원문은 반환하지 않습니다.

package/docs/custom-redirects.md

@@ -25,7 +25,8 @@ description: 어드민 "설정 > 주소 이동"에서 정의한 임의 경로
 
 `@roottale/cms-renderer-next` 의 `createRedirectMiddleware` 를 프로젝트 루트
 `middleware.ts` 에 마운트합니다. 규칙을 자동 캐시(기본 60초)하며, API 실패 시
-트래픽을 막지 않고 통과시킵니다(fail-soft).
+기존 캐시가 있으면 오래된 규칙을 우선 사용하고(stale-first), 캐시가
+없으면 트래픽을 막지 않고 통과시킵니다(fail-soft).
 
 ```ts
 // middleware.ts
@@ -56,8 +57,15 @@ export const config = {
 - 매칭은 **정확 경로 일치**입니다(와일드카드 없음). 출발 경로의 앞/뒤 슬래시와
   한글 percent-encoding 차이는 자동 정규화해 비교합니다.
 - 도착지가 내부 경로면 요청 origin 기준 절대 URL 로 변환해 리다이렉트합니다.
+- 내부 경로 체인은 최종 도착지로 평탄화하고, 순환이 발견되면 브라우저
+  왕복을 막기 위해 해당 요청을 통과시킵니다.
 - 매칭이 없으면 `null` 을 반환하므로 `NextResponse.next()` 로 통과시키세요.
 
+Site Materializer로 새 사이트를 만들면 `middleware.ts`와
+`tests/redirect-middleware.test.ts`가 필수 산출물로 포함됩니다. 두 파일은
+내부 Materializer 영수증에도 기록되므로, 설치 여부를 추측하지 않고
+실제 납품 산출물로 확인할 수 있습니다.
+
 ## 캐시와 즉시성
 
 규칙은 미들웨어가 TTL(기본 60초) 동안 캐시합니다. 운영자가 규칙을 바꾸면

package/docs/inquiries.md

@@ -95,7 +95,7 @@ export async function submitContact(
 ## 유입 어트리뷰션 (`attribution`)
 
 문의가 **어느 글·검색·단축링크/QR에서 왔는지**를 CRM에 표시하려면 두 줄만
-추가하면 됩니다. RootTale 비콘이 방문자의 first-touch(처음 도착한
+추가하면 됩니다. ROOT-ANALYTICS 비콘이 방문자의 first-touch(처음 도착한
 경로·`rt_src` 토큰·utm·외부 referrer 호스트명)를 30일간 기억하며,
 `readAttribution()`(브라우저 전용, `@roottale/cms-client/attribution`)으로
 읽습니다. 식별자가 아니므로 개인정보가 아닙니다.

package/docs/overview.md

@@ -13,10 +13,12 @@ RootTale CMS는 어드민(`admin.roottale.com`)에서 콘텐츠를 작성·발
 
 1. `getting-started.md` — 키 발급 + 환경 설정
 2. `blog.md` — `/blog` 목록·상세 페이지
-3. `revalidation-webhooks.md` — 웹훅 등록 (발행 → 즉시 반영)
-4. `seo.md` — RSS·사이트맵·동적 OG 이미지
-5. `inquiries.md` — 상담문의 폼 (선택)
-6. `menus.md` — 어드민 관리 네비게이션 (선택)
+3. `search.md` — 글·페이지 통합 검색 (선택)
+4. `revalidation-webhooks.md` — 웹훅 등록 (발행 → 즉시 반영)
+5. `seo.md` — RSS·사이트맵·동적 OG 이미지
+6. `theme-and-settings.md` — ROOT-ANALYTICS 연결 (권장)
+7. `inquiries.md` — 상담문의 폼과 유입·여정 저장 (선택)
+8. `menus.md` — 어드민 관리 네비게이션 (선택)
 
 ```
 어드민 (admin.roottale.com)            고객 사이트 (예: example.com)
@@ -34,9 +36,10 @@ RootTale CMS는 어드민(`admin.roottale.com`)에서 콘텐츠를 작성·발
 | 기능 | 같은 키 하나로 |
 |---|---|
 | 블로그 글 목록/상세 조회 | `fetchPosts` / `fetchPost` |
+| 발행 글·페이지 검색 | `searchPosts` / `resolveSearchHitPath` |
 | 발행 웹훅 서명 검증 + 캐시 갱신 | `createRevalidateRoute` (JWKS 공개키 — 별도 secret 보관 불필요). 설정 저장을 즉시 반영하려면 `revalidateTag` 주입 필수 — `revalidation-webhooks.md` §1 |
 | 상담문의(리드) 접수 | `submitInquiry` — 키가 테넌트를 식별 |
-| 테마·블로그 표시·분석 태그 설정 조회 | `fetchTheme` / `fetchBlogSettings` / `fetchAnalyticsConfig` |
+| 테마·블로그 표시·ROOT-ANALYTICS 설정 조회 | `fetchTheme` / `fetchBlogSettings` / `fetchAnalyticsConfig` |
 | 사업장 정보·메뉴·콘텐츠 유형 조회 | `fetchBusinessProfile` / `fetchMenu`·`fetchMenus` / `fetchCollections` |
 
 키는 **서버 전용**입니다. 브라우저로 노출되면 안 됩니다(`NEXT_PUBLIC_*` 금지).
@@ -49,6 +52,7 @@ RootTale CMS는 어드민(`admin.roottale.com`)에서 콘텐츠를 작성·발
 | [`@roottale/cms-client`](https://www.npmjs.com/package/@roottale/cms-client) | 서버 전용 fetch 클라이언트 — 글/테마/설정 조회, 문의 접수, 웹훅 검증 (raw) |
 | [`@roottale/cms-renderer-next`](https://www.npmjs.com/package/@roottale/cms-renderer-next) | Next.js(RSC) 렌더러 — 블로그 컴포넌트, revalidate/RSS/sitemap 라우트 팩토리 |
 | [`@roottale/cms-core`](https://www.npmjs.com/package/@roottale/cms-core) | 블록 JSON 공통 코어 (렌더러가 의존) |
+| [`@roottale/analytics-runtime`](https://www.npmjs.com/package/@roottale/analytics-runtime) | ROOT-ANALYTICS 비콘·동의·Next.js SPA 추적 런타임 |
 | `@roottale/cms-mcp` | 본 MCP 서버 — 통합 문서·예시 코드·API 조회 tool |
 
 ## 문서 맵
@@ -57,9 +61,10 @@ RootTale CMS는 어드민(`admin.roottale.com`)에서 콘텐츠를 작성·발
 |---|---|
 | `getting-started.md` | API 키 발급, 환경변수, 패키지 설치, 첫 조회 |
 | `blog.md` | 블로그 목록/상세 페이지 구현 (컴포넌트 또는 직접 fetch) |
+| `search.md` | 글·페이지 통합 검색, 실제 공개 주소 계산, 보안·캐시·장애 처리 |
 | `revalidation-webhooks.md` | 발행 웹훅으로 near-real-time 캐시 갱신 |
 | `inquiries.md` | 상담문의(리드) 폼 연동 |
 | `menus.md` | 메뉴(네비게이션) — 어드민 "디자인 > 메뉴" 트리를 헤더/푸터에 렌더 |
 | `seo.md` | RSS 피드, 사이트맵, JSON-LD, 동적 OG 이미지, 공개 검색, fleet 프로브 |
-| `theme-and-settings.md` | 디자인 토큰, 블로그 표시 설정, 분석 태그 |
+| `theme-and-settings.md` | 디자인 토큰, 블로그 표시 설정, ROOT-ANALYTICS |
 | `api-reference.md` | HTTP API 레퍼런스 (비 JS 스택용 raw 엔드포인트) |

package/docs/search.md

@@ -0,0 +1,122 @@
+---
+title: 사이트 검색 연동
+description: 발행된 글과 페이지를 서버에서 안전하게 검색하고 실제 공개 주소로 연결
+---
+
+# 사이트 검색 연동
+
+RootTale 검색은 고객 사이트의 **서버**가 공개 CMS API를 호출하는 방식입니다.
+검색창은 일반 GET 폼으로 만들되, `ROOTTALE_API_KEY`는 Server Component나 Route
+Handler 안에서만 사용합니다. 브라우저가 RootTale API를 직접 호출하지 않습니다.
+
+## 권장 구조
+
+```text
+방문자 브라우저
+  GET /search?q=상담
+        │
+        ▼
+고객 사이트 Server Component
+  searchPosts({ type: "all", locale })
+        │  Authorization: Bearer rtlk_cust_*
+        ▼
+RootTale 공개 검색 API
+  tenant + site + locale + published 범위 검색
+```
+
+이 구조는 API 키를 숨기고, 검색 결과 페이지를 서버 렌더링하며, 고객사와 사이트
+경계를 API에서 강제합니다. `NEXT_PUBLIC_ROOTTALE_API_KEY`처럼 공개 환경변수에
+키를 넣으면 안 됩니다.
+
+## Next.js 구현
+
+전체 예시는 `examples/nextjs/app/search/page.tsx`에 있습니다. 핵심 흐름은 다음과
+같습니다.
+
+```tsx
+import {
+  fetchCollections,
+  resolveSearchHitPath,
+  searchPosts,
+} from "@roottale/cms-client/server";
+
+const [hits, collections] = await Promise.all([
+  searchPosts({
+    apiKey: process.env.ROOTTALE_API_KEY!,
+    baseUrl: process.env.ROOTTALE_API_BASE,
+    query,
+    type: "all",
+    locale,
+    limit: 20,
+    revalidate: 60,
+  }),
+  fetchCollections({
+    apiKey: process.env.ROOTTALE_API_KEY!,
+    baseUrl: process.env.ROOTTALE_API_BASE,
+  }).catch(() => []),
+]);
+
+const results = hits.flatMap((hit) => {
+  const href = resolveSearchHitPath(hit, collections, locale);
+  return href ? [{ hit, href }] : [];
+});
+```
+
+사이트 전체 검색은 `type: "all"`을 명시합니다. 이 값을 생략하면 하위 호환을
+위해 글(`post`)만 검색합니다. 다국어 사이트는 현재 경로의 `locale`을 검색 API와
+`resolveSearchHitPath` 양쪽에 같은 값으로 전달합니다.
+
+## 결과 주소 계산
+
+검색 결과의 `slug`만 보고 `/blog/{slug}`를 직접 만들지 않습니다.
+`resolveSearchHitPath`는 다음 규칙을 적용합니다.
+
+| 콘텐츠 | 공개 주소 |
+|---|---|
+| 고정 페이지 | `/{slug}` |
+| 기본 블로그 글 | `/blog/{slug}` |
+| 콘텐츠 유형 글 | `/{collection.basePath}/{slug}` |
+| 다국어 콘텐츠 | 위 주소 앞에 `/{locale}` 추가 |
+| 상세 화면이 없는 콘텐츠 유형 | `null` — 검색 목록에서 제외 |
+
+따라서 `fetchCollections`가 실패해도 일반 글은 `/blog/{slug}`로 연결할 수 있지만,
+공지·자료실 같은 별도 콘텐츠 유형의 주소 정확도를 위해 정상 응답을 권장합니다.
+
+## 검색 범위와 정렬
+
+- API 키에 연결된 tenant와 site 밖의 콘텐츠는 검색하지 않습니다.
+- 요청한 locale의 `published` 콘텐츠만 반환합니다.
+- 제목 완전일치 → 제목 부분일치 → 요약 → 본문 순으로 우선합니다.
+- 같은 점수에서는 최근 발행 콘텐츠가 먼저 나옵니다.
+- 응답은 카드용 슬림 결과이며 본문 전체는 포함하지 않습니다.
+
+현재 한 요청은 최대 50건입니다. 첫 버전에는 페이지네이션, 형태소 분석,
+오타 교정, 동의어 확장이 없습니다. 실제 검색 로그에서 필요성이 확인되면
+추가하는 범위입니다.
+
+## 캐시와 새 글 반영
+
+`revalidate`를 지정하면 Next.js 서버 캐시에 검색 응답이 저장됩니다. 예를 들어
+`revalidate: 60`이면 발행·수정 후 검색 결과가 최대 약 60초 늦게 바뀔 수 있습니다.
+항상 최신 결과가 필요하면 `revalidate: 0`을 사용하되 API 호출량 증가를 고려하세요.
+
+플랫폼 배포 순서는 **migration → API → SDK·고객 사이트**입니다. 검색용 생성 열과
+GIN 색인이 먼저 준비되어야 새 API가 안전하게 조회할 수 있습니다.
+
+## 빈 결과와 장애 처리
+
+- 빈 검색어는 API를 호출하지 않고 입력 안내를 표시합니다.
+- 정상 응답이지만 결과가 없으면 검색어와 함께 `0건` 안내를 표시합니다.
+- API 장애는 빈 결과와 구분해 “잠시 후 다시 시도” 안내를 표시합니다.
+- `searchPosts`는 구 API의 `404`에 한해 빈 배열로 처리하고, 그 밖의 오류는
+  `CmsApiError`로 전달합니다.
+
+검색 입력은 `type="search"`, `name="q"`, 연결된 `<label>`을 사용하고 결과 수는
+`aria-live="polite"`로 알립니다. 검색 결과 페이지는 보통 중복·저가치 URL이므로
+`robots: { index: false, follow: true }`를 권장합니다.
+
+## HTTP API
+
+JavaScript 이외의 서버에서는
+`GET /v1/cms/public/search?q=...&type=all&locale=ko&limit=20`을 사용합니다.
+쿼리와 응답 필드는 [HTTP API 레퍼런스](./api-reference.md)를 참고하세요.

package/docs/seo.md

@@ -591,21 +591,37 @@ export default createPostOgImage(
 
 ## 공개 검색 (사이트 내 검색)
 
-`searchPosts` 로 발행 글 키워드 검색을 붙일 수 있습니다 (WP `?s=` 패리티):
+`searchPosts` 로 발행된 글과 페이지의 통합 검색을 붙일 수 있습니다. API 키는
+브라우저에 보내지 않고 Server Component나 Route Handler에서만 사용합니다:
 
 ```tsx
 // app/search/page.tsx (Server Component)
-import { searchPosts } from "@roottale/cms-client/server";
+import {
+  fetchCollections,
+  resolveSearchHitPath,
+  searchPosts,
+} from "@roottale/cms-client/server";
 
-const hits = await searchPosts({
-  apiKey: process.env.ROOTTALE_API_KEY!,
-  query: q, // ?q= 쿼리
-  limit: 20,
+const [hits, collections] = await Promise.all([
+  searchPosts({
+    apiKey: process.env.ROOTTALE_API_KEY!,
+    query: q, // ?q= 쿼리
+    type: "all", // 글 + 페이지
+    locale: "ko",
+    limit: 20,
+  }),
+  fetchCollections({ apiKey: process.env.ROOTTALE_API_KEY! }),
+]);
+
+const links = hits.flatMap((hit) => {
+  const href = resolveSearchHitPath(hit, collections);
+  return href ? [{ hit, href }] : [];
 });
 // hits: { id, title, slug, excerpt, featuredImageUrl, publishedAt }[]
 ```
 
-본문은 미포함 슬림 hit 이므로 카드에서 `/blog/{slug}` 로 연결하세요.
+본문은 미포함 슬림 hit입니다. 주소를 `/blog/{slug}`로 직접 조립하면 공지·자료실
+등 콘텐츠 유형의 실제 주소를 놓칠 수 있으므로 `resolveSearchHitPath`를 사용하세요.
 검색결과 페이지는 위 체크리스트대로 **noindex** 처리를 잊지 마세요.
 
 ## JSON-LD 스키마 헬퍼

package/docs/theme-and-settings.md

@@ -1,9 +1,9 @@
 ---
-title: 테마·블로그 표시·분석 태그 설정
-description: 어드민에서 관리하는 디자인 토큰, 블로그 표시 옵션, 분석 태그를 사이트에서 조회
+title: 테마·블로그 표시·ROOT-ANALYTICS 설정
+description: 어드민에서 관리하는 디자인 토큰, 블로그 표시 옵션, ROOT-ANALYTICS 설정을 사이트에서 조회
 ---
 
-# 테마·블로그 표시·분석 태그 설정
+# 테마·블로그 표시·ROOT-ANALYTICS 설정
 
 어드민에서 설정한 값을 공개 API로 조회해 사이트에 반영합니다. 모두
 `@roottale/cms-client/server`에서 제공하며 같은 API 키를 사용합니다.
@@ -179,10 +179,10 @@ if (business) {
 > 반환합니다. 전화·주소만 채우고 이름을 비워두면 **나머지 입력이 전부 무시**되니
 > 고객 안내 시 이름을 필수로 안내하세요.
 
-## 분석 태그 — fetchAnalyticsConfig
+## ROOT-ANALYTICS 설정 — fetchAnalyticsConfig
 
-어드민에서 등록한 외부 분석 태그(GA4, Microsoft Clarity, Meta Pixel, 네이버)
-설정을 조회해 사이트에 주입합니다.
+ROOT-ADMIN에서 등록한 외부 태그(GA4, Microsoft Clarity, Meta Pixel, 네이버)와
+ROOT-ANALYTICS 사이트 ID를 조회해 고객 사이트에 연결합니다.
 
 ```ts
 import { fetchAnalyticsConfig } from "@roottale/cms-client/server";
@@ -197,9 +197,9 @@ const config = await fetchAnalyticsConfig({
 `enabled: true`인 태그만 렌더링하세요. 태그 ID는 어드민에서 변경될 수
 있으므로 하드코딩하지 말고 본 API로 조회하는 것을 권장합니다.
 
-## 조회수 / first-party 비콘
+## ROOT-ANALYTICS 조회수·first-party 비콘
 
-RootTale 비콘은 쿠키리스 first-party 분석(방문수·클릭)과 **글별 조회수**를
+ROOT-ANALYTICS 비콘은 쿠키리스 first-party 분석(페이지·클릭)과 **글별 조회수**를
 수집합니다. **API 키 하나로** 동작합니다 — 별도 사이트 ID 환경변수가 필요 없습니다.
 `fetchAnalyticsConfig`가 돌려주는 `siteId`를 비콘에 그대로 넘기세요.
 
@@ -240,10 +240,21 @@ export async function generateMetadata({ params }): Promise<Metadata> {
 > `@roottale/cms-client/server`의 `contentIdMeta(post.id)`가 같은 `<meta>` 태그
 > 문자열을 만들어 줍니다.
 
-수집은 익명·쿠키리스이며 비콘은 클릭(`data-track`)과 pageview만 보냅니다. 봇
-트래픽은 서버에서 제외됩니다. 공개 사이트에 "조회 N"을 표시하는 옵션은 어드민의
+수집은 익명·쿠키리스이며 비콘은 pageview와 명시한 행동 이벤트를 보냅니다. Next.js
+SPA 전환과 섹션·스크롤·읽기·폼 감지는 `@roottale/analytics-runtime/next` 어댑터로
+연결합니다. 봇 트래픽은 서버에서 제외됩니다. 공개 사이트에 "조회 N"을 표시하는 옵션은 어드민의
 사이트 설정에서 켤 수 있습니다(켜면 글 응답에 `view_count`가 포함됩니다).
 
+저장 위치는 데이터 성격에 따라 나뉩니다.
+
+| 데이터 | 저장 위치 |
+|---|---|
+| 페이지·클릭·섹션 이벤트 | Cloudflare Analytics Engine `cms_site_events` |
+| 글 누적 조회수 | 사이트별 Durable Object SQLite, PostgreSQL `posts.view_count` 미러 |
+| 첫·마지막 유입 | 브라우저 `localStorage._rt_attr`(30일) |
+| 현재 방문 여정 | 브라우저 `sessionStorage._rt_journey`(최대 30건) |
+| 문의에 귀속된 유입·여정 | PostgreSQL `inquiries.attribution`, `inquiries.journey` |
+
 ## 사이트 지식 — 브랜드 보이스 (AI 에이전트용)
 
 이 사이트의 **브랜드 보이스**(어조·톤·화자)와 **용어 규칙**(금지어·교정어)을

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

@@ -0,0 +1,64 @@
+// 사이트 통합 검색 — 고객 브라우저가 아니라 이 Server Component가 CMS API를 호출한다.
+import type { Metadata } from "next";
+import Link from "next/link";
+
+import {
+  fetchCollections,
+  resolveSearchHitPath,
+  searchPosts,
+} from "@roottale/cms-client/server";
+
+export const metadata: Metadata = {
+  title: "사이트 검색",
+  robots: { index: false, follow: true },
+};
+
+interface Props {
+  searchParams: Promise<{ q?: string | string[] }>;
+}
+
+export default async function SearchPage({ searchParams }: Props) {
+  const { q = "" } = await searchParams;
+  const query = (typeof q === "string" ? q : q[0] ?? "").trim();
+  const apiKey = process.env.ROOTTALE_API_KEY!;
+  const baseUrl = process.env.ROOTTALE_API_BASE;
+  const [hits, collections] = query
+    ? await Promise.all([
+        searchPosts({ apiKey, baseUrl, query, type: "all", limit: 20 }),
+        fetchCollections({ apiKey, baseUrl }).catch(() => []),
+      ])
+    : [[], []];
+
+  return (
+    <main>
+      <h1>사이트 검색</h1>
+      <form action="/search" method="get" role="search">
+        <label htmlFor="site-search">검색어</label>
+        <input
+          defaultValue={query}
+          id="site-search"
+          maxLength={100}
+          name="q"
+          required
+          type="search"
+        />
+        <button type="submit">검색</button>
+      </form>
+      {query ? <p>검색 결과 {hits.length}건</p> : <p>검색어를 입력해 주세요.</p>}
+      <ul>
+        {hits.map((hit) => {
+          const href = resolveSearchHitPath(hit, collections);
+          if (!href) return null;
+          return (
+            <li key={hit.id}>
+              <Link href={href}>
+                <h2>{hit.title}</h2>
+                {hit.excerpt ? <p>{hit.excerpt}</p> : null}
+              </Link>
+            </li>
+          );
+        })}
+      </ul>
+    </main>
+  );
+}

package/examples/nextjs/components/global-popup.tsx

@@ -0,0 +1,13 @@
+import { RootTaleExposureSlot } from "@roottale/cms-renderer-next/server";
+
+export async function GlobalPopup({ path }: { path: string }) {
+  return (
+    <RootTaleExposureSlot
+      apiKey={process.env.ROOTTALE_API_KEY!}
+      slotKey="global-popup"
+      path={path}
+      allowedVariants={["card", "image-card"]}
+      revalidate={60}
+    />
+  );
+}

package/examples/nextjs/middleware.ts

@@ -2,7 +2,8 @@
 //
 // 글 슬러그 변경 자동 301 은 글 라우트에서 처리되지만(blog 예시 참고), 글이
 // 아닌 임의 경로(`/old-event → /promo`)는 라우팅 이전 단계인 미들웨어에서만
-// 가로챌 수 있다. 규칙은 자동 캐시되고, API 실패 시 트래픽을 막지 않는다.
+// 가로챌 수 있다. 규칙은 자동 캐시되고, API 실패 시 stale 캐시를
+// 우선 사용한다. 캐시가 없거나 순환 규칙이면 트래픽을 막지 않는다.
 import { NextResponse } from "next/server";
 import { createRedirectMiddleware } from "@roottale/cms-renderer-next/routes";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roottale/cms-mcp",
-  "version": "0.53.0",
+  "version": "0.53.1",
   "type": "module",
   "description": "RootTale CMS MCP server and CLI for post publishing, media uploads, integration docs, and public API access.",
   "bin": {