@roottale/cms-mcp 0.22.0

package/docs/blog.md

@@ -0,0 +1,172 @@
+---
+title: 블로그 연동
+description: 블로그 목록/상세 페이지 구현 — 컴포넌트 빠른 경로와 직접 fetch 커스텀 경로
+---
+
+# 블로그 연동
+
+두 가지 경로가 있습니다:
+
+- **빠른 경로** — `@roottale/cms-renderer-next`의 RSC 컴포넌트 사용. 데이터
+  fetch + 렌더링까지 한 번에.
+- **커스텀 경로** — `@roottale/cms-client`로 raw 데이터를 가져와 자체 UI로
+  렌더링. 디자인을 완전히 통제할 때.
+
+본문 렌더링은 두 경로 모두 `RootTaleBlogPost`(블록 JSON → React)를 쓰는 것을
+권장합니다. 본문 JSON 스키마를 직접 파싱하지 마세요.
+
+## 빠른 경로 — 컴포넌트
+
+### 목록 페이지
+
+```tsx
+// app/blog/page.tsx
+import { RootTaleBlogList } from "@roottale/cms-renderer-next/server";
+
+export const revalidate = 1800; // 30분 fallback — 실시간 갱신은 웹훅이 담당
+
+export default function BlogPage() {
+  return (
+    <RootTaleBlogList
+      apiKey={process.env.ROOTTALE_API_KEY!}
+      baseUrl={process.env.ROOTTALE_API_BASE}
+      limit={20}
+      showCategoryFilter
+      postHref={(post) => `/blog/${post.slug}`}
+    />
+  );
+}
+```
+
+### 상세 페이지
+
+```tsx
+// app/blog/[slug]/page.tsx
+import { RootTaleBlogPost } from "@roottale/cms-renderer-next/server";
+
+export const revalidate = 1800;
+
+export default async function PostPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params; // Next.js 15+ async params
+  return (
+    <RootTaleBlogPost
+      apiKey={process.env.ROOTTALE_API_KEY!}
+      baseUrl={process.env.ROOTTALE_API_BASE}
+      slugOrId={slug}
+      showTableOfContents
+      tableOfContentsTitle="목차"
+    />
+  );
+}
+```
+
+목차(ToC)·작성자 카드·발행일 표시는 어드민의 블로그 표시 설정으로도 제어됩니다
+(`theme-and-settings.md` 참고).
+
+### 고정 페이지 (회사소개 등)
+
+어드민의 고정 페이지(`type: "page"`)는 `RootTalePage`로 렌더링합니다 — 블로그
+크롬(날짜·작성자·작성자 카드) 없이 제목+본문만 출력합니다 (renderer-next
+0.22.0+):
+
+```tsx
+// app/about/page.tsx
+import { RootTalePage } from "@roottale/cms-renderer-next/server";
+
+export const revalidate = 1800;
+
+export default function AboutPage() {
+  return (
+    <RootTalePage
+      apiKey={process.env.ROOTTALE_API_KEY!}
+      baseUrl={process.env.ROOTTALE_API_BASE}
+      slugOrId="about"
+      // showTitle={false} — 페이지 제목을 직접 마크업할 때
+    />
+  );
+}
+```
+
+## 커스텀 경로 — 직접 fetch
+
+```ts
+// lib/blog.ts
+import { fetchPosts, fetchPost, type CmsPostContent } from "@roottale/cms-client/server";
+
+export async function getAllPosts() {
+  const page = await fetchPosts({
+    apiKey: process.env.ROOTTALE_API_KEY!,
+    baseUrl: process.env.ROOTTALE_API_BASE,
+    type: "post",
+    limit: 100,
+  });
+  return page.items; // CmsPostContent[]
+  // page.hasMore / page.nextCursor 로 커서 페이지네이션
+}
+
+export async function getPost(slug: string) {
+  return fetchPost({
+    apiKey: process.env.ROOTTALE_API_KEY!,
+    baseUrl: process.env.ROOTTALE_API_BASE,
+    slugOrId: slug, // slug 또는 UUID — 404면 null 반환
+  });
+}
+```
+
+`CmsPostContent` 주요 필드:
+
+| 필드 | 설명 |
+|---|---|
+| `id`, `slug`, `title` | 식별자·제목 |
+| `excerpt` | 요약 (목록 카드용) |
+| `publishedAt` | 발행 시각 (ISO) |
+| `bodyJson` | 본문 블록 JSON — `RootTaleBlogPost` 또는 `renderBlocks`로 렌더 |
+| `terms` | 분류 용어 배열 (`taxonomy: "category" \| "tag"`, `name`, `slug`) |
+| `featuredImageUrl` | 대표 이미지 |
+| `authorName` | 작성자 표시명 |
+| `metaJson` | 부가 메타 — `metaJson.seo`에 SEO 오버라이드 |
+
+### 정적 경로 사전 생성 + 메타데이터
+
+```tsx
+// app/blog/[slug]/page.tsx (커스텀 UI 버전)
+import type { Metadata } from "next";
+import { getAllPosts, getPost } from "@/lib/blog";
+
+export async function generateStaticParams() {
+  const posts = await getAllPosts();
+  return posts.map((p) => ({ slug: p.slug }));
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}): Promise<Metadata> {
+  const { slug } = await params;
+  const post = await getPost(slug);
+  if (!post) return {};
+  // 어드민 글 에디터의 SEO 패널 값(metaJson.seo)을 우선 적용
+  const seo = (post.metaJson as { seo?: Record<string, string | boolean> })?.seo;
+  return {
+    title: (seo?.title as string) || post.title,
+    description: (seo?.description as string) || post.excerpt,
+    ...(seo?.noindex ? { robots: { index: false, follow: true } } : {}),
+  };
+}
+```
+
+SEO 오버라이드 필드: `title`, `description`, `canonical`, `ogImage`, `noindex`.
+
+## 캐싱 전략
+
+- 페이지에 `export const revalidate = 1800` (30분) — **fallback일 뿐**입니다.
+- 정상 동작은 발행 웹훅이 즉시 revalidate 하는 것 → `revalidation-webhooks.md`
+  를 반드시 함께 설정하세요.
+- 홈 화면에 최신 글 섹션을 둔다면 홈도 웹훅의 `alsoRevalidate`에 포함하세요.
+
+완전한 동작 예시는 MCP tool `readRootTaleNextjsExampleCode`로 확인할 수 있습니다.

package/docs/getting-started.md

@@ -0,0 +1,78 @@
+---
+title: 시작하기
+description: API 키 발급, 환경변수 설정, 패키지 설치, 첫 콘텐츠 조회
+---
+
+# 시작하기
+
+## 1. API 키 발급
+
+1. 어드민(`mysite.roottale.com`) 로그인
+2. **설정 > 사이트 연결 키** 메뉴로 이동
+3. 새 키 발급 — 권한 선택:
+   - **read** (기본): 발행된 콘텐츠 조회만. 외부 사이트 연동은 이걸로 충분
+   - **read_write**: 쓰기 포함 (자동화 서버용 — 일반 연동에는 불필요)
+4. 발급된 키(`rtlk_cust_` + 24자)는 **발급 직후 1회만 평문 표시**됩니다. 바로
+   복사해 환경변수에 저장하세요.
+
+키는 사이트 단위로 스코프되어(site-scoped) 해당 사이트의 콘텐츠·웹훅 검증에만
+사용됩니다.
+
+## 2. 환경변수
+
+```bash
+# .env.local (Next.js) 또는 배포 플랫폼의 환경변수 — 반드시 서버 전용
+ROOTTALE_API_KEY=rtlk_cust_xxxxxxxxxxxxxxxxxxxxxxxx
+
+# (선택) API 베이스 오버라이드 — 기본값 https://api.roottale.com 이면 생략
+# ROOTTALE_API_BASE=https://api.roottale.com
+
+# 사이트 정식 도메인 (RSS/sitemap/canonical 생성용)
+NEXT_PUBLIC_SITE_URL=https://example.com
+```
+
+**중요**: `ROOTTALE_API_KEY`는 절대 `NEXT_PUBLIC_*` 접두를 붙이지 마세요.
+브라우저로 노출되면 누구나 그 키로 API를 호출할 수 있습니다.
+`@roottale/cms-client`는 브라우저에서 실행되면 의도적으로 에러를 던집니다.
+
+## 3. 패키지 설치
+
+```bash
+# Next.js 사이트
+npm install @roottale/cms-client @roottale/cms-renderer-next
+# 또는
+pnpm add @roottale/cms-client @roottale/cms-renderer-next
+```
+
+요구사항: Node ≥ 18.18, React 19, Next.js 14+ (renderer-next 사용 시).
+
+렌더러 스타일은 root layout에서 1회 import:
+
+```ts
+// app/layout.tsx
+import "@roottale/cms-renderer-next/styles";
+```
+
+## 4. 첫 조회 — 동작 확인
+
+```ts
+// 서버 컴포넌트, Route Handler, 또는 빌드 스크립트에서
+import { fetchPosts } from "@roottale/cms-client/server";
+
+const page = await fetchPosts({
+  apiKey: process.env.ROOTTALE_API_KEY!,
+  limit: 5,
+  type: "post",
+});
+console.log(page.items.map((p) => p.slug));
+```
+
+응답이 비어 있다면 어드민에서 글이 **발행(published)** 상태인지 확인하세요.
+공개 API는 발행된 콘텐츠만 반환합니다.
+
+`401` 에러(`invalid_key`)면 키 값/환경변수 로딩을 확인하세요.
+
+## 다음 단계
+
+- 블로그 페이지 구현 → `blog.md`
+- 발행 즉시 사이트 반영 → `revalidation-webhooks.md`

package/docs/inquiries.md

@@ -0,0 +1,114 @@
+---
+title: 상담문의(리드) 연동
+description: submitInquiry 서버 액션으로 문의 폼을 어드민 CRM에 연결
+---
+
+# 상담문의(리드) 연동
+
+사이트의 문의 폼 제출을 RootTale로 보내면 어드민 **CRM(받은문의)** 에서
+관리됩니다. 블로그 조회와 **같은 API 키 하나**로 동작하며, 키가 테넌트를
+식별하므로 별도 식별자가 필요 없습니다. 개인정보(이름·연락처 등)는 서버에서
+암호화 저장됩니다.
+
+## 권장 — Next.js Server Action
+
+```ts
+// lib/actions/submit-contact.ts
+"use server";
+
+import { submitInquiry } from "@roottale/cms-client/server";
+
+export interface ContactState {
+  status: "idle" | "success" | "error";
+  message?: string;
+  errors?: Partial<Record<"name" | "phone" | "privacyConsent", string>>;
+}
+
+export async function submitContact(
+  _prev: ContactState,
+  formData: FormData,
+): Promise<ContactState> {
+  const name = (formData.get("name") as string | null)?.trim() ?? "";
+  const phone = (formData.get("phone") as string | null)?.trim() ?? "";
+  const message = (formData.get("message") as string | null)?.trim() ?? "";
+  const privacyConsent = formData.get("privacyConsent") !== null;
+
+  const errors: ContactState["errors"] = {};
+  if (!name) errors.name = "이름을 입력해주세요.";
+  if (!phone || phone.length < 7) errors.phone = "연락처를 입력해주세요.";
+  if (!privacyConsent) errors.privacyConsent = "개인정보 수집·이용에 동의해주세요.";
+  if (Object.keys(errors).length > 0) {
+    return { status: "error", message: "필수 항목을 입력해주세요.", errors };
+  }
+
+  const result = await submitInquiry({
+    apiKey: process.env.ROOTTALE_API_KEY!,
+    baseUrl: process.env.ROOTTALE_API_BASE,
+    fields: {
+      vertical: "tax", // consulting | medical | tax | legal
+      contactName: name,
+      businessName: name, // 사업체명 미수집 폼이면 이름으로 대체
+      email: `noemail-${name}@example.invalid`, // 이메일 미수집 폼이면 placeholder
+      phone, // 자동으로 010-1234-5678 형태 포맷됨
+      message: message || undefined,
+      privacyConsent: true, // 사용자가 명시 동의한 경우에만 true
+    },
+  });
+
+  if (result.ok) {
+    return { status: "success", message: "상담 문의가 접수되었습니다." };
+  }
+  return { status: "error", message: result.message };
+}
+```
+
+클라이언트 폼에서는 `useActionState(submitContact, { status: "idle" })`로
+연결합니다.
+
+## 필드 레퍼런스 (`SubmitInquiryFields`)
+
+| 필드 | 필수 | 설명 |
+|---|---|---|
+| `vertical` | ✅ | `consulting` \| `medical` \| `tax` \| `legal` |
+| `contactName` | ✅ | 이름 |
+| `businessName` | ✅ | 사업체명 (미수집 시 이름으로 대체) |
+| `email` | ✅ | 이메일 (`.+@.+\..+`) |
+| `phone` | ✅ | 전화번호 (자동 한국식 포맷) |
+| `privacyConsent` | ✅ | 개인정보 수집·이용 동의 — 반드시 사용자 명시 동의 |
+| `message` | | 문의 내용 |
+| `consultationField` | | 상담 분야 라벨 |
+| `currentSiteUrl` | | 현재 사이트 URL |
+| `overseasTransferConsent` | medical 시 ✅ | 국외이전 동의 |
+| `leadKind` | | `patient`(기본) \| `sales` |
+| `extras` | | 임의 추가 항목 (최대 50개, 암호화 보관, CRM 상세에 노출) |
+
+`extras`에 개인정보가 담길 수 있으므로 폼의 동의 고지에 수집 항목을 반영하세요.
+
+## 에러 처리
+
+`submitInquiry`는 throw 하지 않고 구조화된 결과를 반환합니다:
+
+```ts
+type SubmitInquiryResult =
+  | { ok: true }
+  | { ok: false; code: string | null; message: string }; // message = 한국어 사용자 메시지
+```
+
+| `code` | 의미 |
+|---|---|
+| `consent_privacy` | 개인정보 동의 누락 |
+| `consent_overseas` | medical인데 국외이전 동의 누락 |
+| `missing_fields` | 필수 필드 누락 |
+| `invalid_email` | 이메일 형식 오류 |
+| `invalid_vertical` | 허용되지 않는 vertical |
+| `invalid_api_key` | 키 인증 실패 |
+| `internal` | 서버/네트워크 오류 |
+
+## 대안 — RootTaleLeadForm 컴포넌트
+
+자체 폼 없이 빠르게 붙일 때는 `@roottale/cms-renderer-next`의
+`RootTaleLeadForm`(RSC, HTML form)을 사용할 수 있습니다. 디자인·검증을
+통제하려면 위의 Server Action 방식을 권장합니다.
+
+raw HTTP로 직접 연동(비 JS 스택)하려면 `api-reference.md`의
+`POST /v1/public/inquiries`를 참고하세요.

package/docs/overview.md

@@ -0,0 +1,63 @@
+---
+title: RootTale CMS 연동 개요
+description: 연동 아키텍처, 단일 API 키 모델, 패키지 구성, 문서 맵
+---
+
+# RootTale CMS 연동 개요
+
+RootTale CMS는 어드민(`mysite.roottale.com`)에서 콘텐츠를 작성·발행하고, 외부
+고객 사이트(자체 도메인의 Next.js/Astro 등)가 공개 API(`api.roottale.com`)로
+콘텐츠를 가져가는 헤드리스 구조입니다.
+
+```
+어드민 (mysite.roottale.com)            고객 사이트 (예: example.com)
+  글 작성·발행 ──────────┐
+                         ▼
+              api.roottale.com  ◀── Bearer rtlk_cust_* ── 콘텐츠/설정 조회
+                         │
+  발행 웹훅 (ES256 서명) ─┴──────────▶ POST /api/revalidate → 캐시 즉시 갱신
+```
+
+## 단일 API 키 모델
+
+연동 전체가 **API 키 하나(`rtlk_cust_*`)** 로 동작합니다:
+
+| 기능 | 같은 키 하나로 |
+|---|---|
+| 블로그 글 목록/상세 조회 | `fetchPosts` / `fetchPost` |
+| 발행 웹훅 서명 검증 | `createRevalidateRoute` (JWKS 공개키 — 별도 secret 보관 불필요) |
+| 상담문의(리드) 접수 | `submitInquiry` — 키가 테넌트를 식별 |
+| 테마·블로그 표시·분석 태그 설정 조회 | `fetchTheme` / `fetchBlogSettings` / `fetchAnalyticsConfig` |
+
+키는 **서버 전용**입니다. 브라우저로 노출되면 안 됩니다(`NEXT_PUBLIC_*` 금지).
+`@roottale/cms-client`는 브라우저에서 import 시 의도적으로 throw 합니다.
+
+## 패키지 구성 (npm public)
+
+| 패키지 | 역할 |
+|---|---|
+| [`@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-renderer-astro`](https://www.npmjs.com/package/@roottale/cms-renderer-astro) | Astro 렌더러 |
+| [`@roottale/cms-core`](https://www.npmjs.com/package/@roottale/cms-core) | 블록 JSON 공통 코어 (렌더러들이 의존) |
+| `@roottale/cms-mcp` | 본 MCP 서버 — 통합 문서·예시 코드·API 조회 tool |
+
+## 문서 맵
+
+| 문서 | 내용 |
+|---|---|
+| `getting-started.md` | API 키 발급, 환경변수, 패키지 설치, 첫 조회 |
+| `blog.md` | 블로그 목록/상세 페이지 구현 (컴포넌트 또는 직접 fetch) |
+| `revalidation-webhooks.md` | 발행 웹훅으로 near-real-time 캐시 갱신 |
+| `inquiries.md` | 상담문의(리드) 폼 연동 |
+| `seo.md` | RSS 피드, 사이트맵, JSON-LD, fleet 프로브 |
+| `theme-and-settings.md` | 디자인 토큰, 블로그 표시 설정, 분석 태그 |
+| `api-reference.md` | HTTP API 레퍼런스 (비 JS 스택용 raw 엔드포인트) |
+
+## 권장 연동 순서
+
+1. `getting-started.md` — 키 발급 + 환경 설정
+2. `blog.md` — `/blog` 목록·상세 페이지
+3. `revalidation-webhooks.md` — 웹훅 등록 (발행 → 즉시 반영)
+4. `seo.md` — RSS·사이트맵
+5. `inquiries.md` — 상담문의 폼 (선택)

package/docs/revalidation-webhooks.md

@@ -0,0 +1,129 @@
+---
+title: 발행 웹훅 (캐시 자동 갱신)
+description: 글 발행/수정 시 사이트 캐시를 near-real-time으로 갱신하는 웹훅 설정
+---
+
+# 발행 웹훅 — 캐시 자동 갱신
+
+어드민에서 글을 발행/수정/삭제하면 RootTale이 고객 사이트의 revalidate
+엔드포인트로 **ES256 서명된 웹훅**을 보냅니다. 사이트는 서명을 검증하고
+`revalidatePath`를 호출해 즉시 갱신합니다.
+
+- 별도 webhook secret을 보관할 필요가 없습니다 — 검증은 사이트 스코프 API
+  키로 JWKS 공개키를 가져와 수행합니다.
+- ISR `revalidate = 1800` 같은 시간 기반 설정은 **fallback**입니다. 정상
+  경로는 웹훅입니다.
+
+## 1. revalidate 라우트 추가 (Next.js)
+
+```ts
+// app/api/revalidate/route.ts
+import { revalidatePath } from "next/cache";
+import { createRevalidateRoute } from "@roottale/cms-renderer-next/routes";
+
+export const POST = createRevalidateRoute({
+  apiKey: process.env.ROOTTALE_API_KEY!,
+  apiBase: process.env.ROOTTALE_API_BASE,
+  revalidate: revalidatePath,
+  // 글 변경 시 함께 갱신할 추가 경로 (기본: /feed.xml, /sitemap.xml, /blog)
+  alsoRevalidate: ["/feed.xml", "/sitemap.xml", "/blog", "/"],
+});
+
+export function GET(): Response {
+  return new Response("Method Not Allowed", { status: 405 });
+}
+```
+
+블로그가 `/blog`가 아닌 경로면 `blogBasePath: "/insights"` 옵션을 추가하세요.
+
+카테고리/태그 인덱스 같은 동적 경로가 있다면 `revalidate` 콜백을 확장합니다:
+
+```ts
+function revalidateBlogPath(path: string): void {
+  revalidatePath(path);
+  if (path === "/blog/categories") revalidatePath("/blog/categories/[category]", "page");
+  if (path === "/blog/tags") revalidatePath("/blog/tags/[tag]", "page");
+}
+```
+
+## 2. 어드민에 웹훅 URL 등록
+
+1. 어드민 **내 사이트 > (사이트 선택)** 페이지로 이동
+2. "글 발행 후 사이트 자동 갱신" 카드에서:
+   - **자동 갱신 URL**: `https://<사이트 도메인>/api/revalidate`
+   - **활성화** 체크
+3. 저장 — ES256 키페어가 자동 발급됩니다 (고객 측 보관 항목 없음)
+
+URL을 비우고 저장하면 웹훅이 비활성화됩니다.
+
+## 웹훅 발송 트리거
+
+- 게시물 생성/발행/수정/삭제/발행 취소
+- 게시물의 카테고리·태그 변경 (블로그 카드의 카테고리 라벨이 바뀌므로)
+- 분류(taxonomy) 용어 삭제 (해당 용어를 참조하던 발행 글 전부)
+- 블로그 표시 설정 변경 (TOC, 작성자/발행일, 작성자 카드)
+- 디자인 토큰 변경
+- 수동 revalidation API 호출
+
+## 캐시 무효화 규칙
+
+수신 측은 다음을 보장해야 합니다 (`createRevalidateRoute`가 기본 처리):
+
+- 모든 서명된 이벤트에서 블로그 목록(`/blog`) revalidate — 글 본문이 안
+  바뀌어도 카드 메타(카테고리 라벨 등)가 바뀔 수 있음
+- 상세 페이지는 현재 slug + payload의 `paths` 힌트 경로 모두 revalidate
+- 홈에 최신 글 섹션이 있으면 `alsoRevalidate`에 `/` 포함
+
+## 저수준 검증 — verifyRootTaleWebhook
+
+`createRevalidateRoute`를 못 쓰는 환경(다른 프레임워크 등)은
+`@roottale/cms-client/webhook`으로 직접 검증합니다:
+
+```ts
+import { verifyRootTaleWebhook } from "@roottale/cms-client/webhook";
+
+export async function POST(request: Request) {
+  const rawBody = await request.text(); // 반드시 파싱 전 raw로 검증
+  const result = await verifyRootTaleWebhook({
+    rawBody,
+    headers: request.headers,
+    apiKey: process.env.ROOTTALE_API_KEY!,
+  });
+  if (!result.ok) {
+    return Response.json({ reason: result.reason }, { status: 401 });
+  }
+  // result.event: "post.published" | "post.updated" | "post.deleted"
+  // result.payload.paths: 갱신할 root-relative 경로 배열
+  return Response.json({ ok: true });
+}
+```
+
+실패 `reason` 값: `missing_signature`, `invalid_signature`, `expired`,
+`body_hash_mismatch`, `timestamp_out_of_window`, `replay_seen` 등.
+옵션으로 `expectedSiteId`(멀티 사이트 하드닝), `consumeJti`(replay 방지 저장소),
+`timestampWindowSec`(기본 300초)을 지정할 수 있습니다.
+
+## 수동 revalidation API
+
+배포 직후 등 강제 갱신이 필요할 때:
+
+```http
+POST https://api.roottale.com/v1/cms/revalidate
+Authorization: Bearer rtlk_cust_...
+Content-Type: application/json
+
+{
+  "event": "post.updated",
+  "paths": ["/blog", "/blog/my-post"],
+  "slug": "my-post"
+}
+```
+
+## 트러블슈팅
+
+| 증상 | 확인 |
+|---|---|
+| 발행해도 사이트 미반영 | 어드민의 자동 갱신 URL·활성화 체크, 배포 도메인 일치 여부 |
+| 401 `invalid_signature` | `ROOTTALE_API_KEY`가 해당 사이트 스코프 키인지 |
+| 401 `timestamp_out_of_window` | 서버 시계 동기화 (NTP) |
+| 일부 페이지만 갱신 | `alsoRevalidate`·동적 경로 콜백 누락 |

package/docs/seo.md

@@ -0,0 +1,103 @@
+---
+title: SEO (RSS·사이트맵·JSON-LD)
+description: RSS 피드, 사이트맵, JSON-LD 스키마, fleet 프로브 라우트
+---
+
+# SEO — RSS·사이트맵·JSON-LD
+
+`@roottale/cms-renderer-next/routes`의 팩토리로 RSS·사이트맵을 한 줄에
+구성하고, `@roottale/cms-client/server`의 헬퍼로 JSON-LD를 생성합니다.
+
+## RSS 피드
+
+```ts
+// app/feed.xml/route.ts
+import { createFeedRoute } from "@roottale/cms-renderer-next/routes";
+
+export const dynamic = "force-dynamic";
+
+export const GET = createFeedRoute({
+  apiKey: process.env.ROOTTALE_API_KEY!,
+  apiBase: process.env.ROOTTALE_API_BASE,
+  siteUrl: process.env.NEXT_PUBLIC_SITE_URL!,
+  title: "예시 블로그",
+  description: "예시 블로그 설명",
+});
+```
+
+발행된 글이 자동 포함된 RSS 2.0 XML을 반환합니다.
+
+## 사이트맵
+
+```ts
+// app/sitemap.ts
+import { createSitemap } from "@roottale/cms-renderer-next/routes";
+
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL!;
+
+export default createSitemap(
+  {
+    apiKey: process.env.ROOTTALE_API_KEY!,
+    apiBase: process.env.ROOTTALE_API_BASE,
+    siteUrl: SITE_URL,
+    title: "예시 사이트",
+  },
+  [
+    // 정적 경로 — 발행 글 URL은 자동 추가됨
+    { url: SITE_URL, changeFrequency: "weekly", priority: 1.0 },
+    { url: `${SITE_URL}/blog`, changeFrequency: "weekly", priority: 0.7 },
+    { url: `${SITE_URL}/contact`, changeFrequency: "monthly", priority: 0.9 },
+  ],
+);
+```
+
+## RSS/사이트맵과 웹훅
+
+발행 웹훅의 `alsoRevalidate`에 `/feed.xml`, `/sitemap.xml`을 포함해 글 변경
+시 함께 갱신하세요 (`revalidation-webhooks.md` 참고).
+
+## JSON-LD 스키마 헬퍼
+
+`@roottale/cms-client/server`에서 제공:
+
+| 함수 | 용도 |
+|---|---|
+| `articleSchema(input)` | 블로그 글 상세 페이지 Article |
+| `breadcrumbSchema(items)` | 빵부스러기 |
+| `organizationSchema(input)` | 조직/사업체 |
+| `websiteSchema(input)` | 웹사이트 |
+| `faqSchema(items)` | FAQ |
+
+```tsx
+import { articleSchema } from "@roottale/cms-client/server";
+
+const jsonLd = articleSchema({
+  title: post.title,
+  description: post.excerpt,
+  url: `${SITE_URL}/blog/${post.slug}`,
+  datePublished: post.publishedAt,
+  image: post.featuredImageUrl ?? undefined,
+});
+
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+/>;
+```
+
+저수준 RSS가 필요하면 `generateRssXml` / `rssItemsFromPosts`를 직접 사용할 수
+있습니다.
+
+## Fleet 프로브 (운영 가시성)
+
+RootTale 운영 측이 배포 버전·헬스를 확인할 수 있는 well-known 라우트:
+
+```ts
+// app/.well-known/roottale.json/route.ts
+import { createFleetInfoRoute } from "@roottale/cms-renderer-next/routes";
+
+export const GET = createFleetInfoRoute({ site: "example" });
+```
+
+`site`에는 사이트 식별용 슬러그를 넣습니다. 필수는 아니지만 운영 지원을
+받으려면 추가를 권장합니다.