@roottale/cms-mcp 0.55.0 → 0.57.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @roottale/cms-mcp
 
+## 0.57.0
+
+### Minor Changes
+
+- e222471: 본문 예약 내부 링크(`[[internal:키|문구]]`)를 공용 렌더러가 해석한다.
+  - `@roottale/cms-core`: 토큰 정규식·탐색(`findInternalContentLinkTokens`), 경로→키
+    (`internalContentKeyFromPath`), 발행 글 경로 색인(`internalContentPathIndex`, 옛 slug 포함),
+    텍스트·정화된 HTML 안의 토큰을 링크로 바꾸는 `renderInternalContentLinksInText/InHtml`.
+  - `@roottale/cms-renderer-next`: `RenderTiptap`·`RootTaleBlogPost` 에 `internalLinks`
+    (Map·함수) 옵션. `RootTaleBlogPost` 는 기본 `"auto"` — 본문에 토큰이 있을 때만
+    `fetchInternalContentPathIndex` 로 발행 글 경로 색인을 만들어 링크로 렌더한다.
+    대상이 없는 토큰은 문구만 남기고 `data-rt-internal-link-pending="키"` 를 단다.
+    `<code>`·`<pre>`·기존 링크 안은 건드리지 않는다.
+  - 문서: FRONT 가 토큰을 직접 해석하지 않아도 되는 경로를 안내한다.
+
+- 92d0ad4: 공통 블록(Site Patterns) — 여러 글의 같은 자리(글 하단)에 붙는 재사용 본문.
+  - `@roottale/cms-client`: 글 응답 `patternSlots`(자리 key → 블록 key | null, 구 서버는 빈
+    객체), `fetchSitePatterns`(발행 블록 목록, `GET /v1/cms/public/patterns`),
+    `selectSitePatternForSlot`, `SITE_PATTERNS_CACHE_TAG`(`SETTINGS_CACHE_TAGS` 에 포함 —
+    `theme.updated` 로 함께 갱신), `POST_FOOTER_PATTERN_SLOT`.
+  - `@roottale/cms-renderer-next`: `RootTaleBlogPost` 가 `patternSlots.post_footer` 블록을 본문
+    바로 아래에 자동으로 그린다(목록 요청 실패는 블록만 생략). 자체 글 화면용
+    `RootTalePostPattern` 서버 컴포넌트와 `.rt-cms-post-pattern` 스타일 추가.
+  - `@roottale/cms-core`: 자리 선언·배치 규칙 정규화·`resolvePatternSlots` (플랫폼 서버·어드민과
+    공유하는 순수 규칙).
+  - 문서: `theme-and-settings.md` "공통 블록", `api-reference.md` `GET /patterns`·`pattern_slots`.
+
+## 0.56.0
+
+### Patch Changes
+
+- 18aaa9e: ADR-0105 Amendment 1 — 공개 글 응답에 저장된 정규 공개 경로 `path`(cms-client
+  `post.path`)를 additive 로 더합니다. FRONT 는 주소를 계산하지 않고 이 값을 링크·사이트맵·
+  내부 링크 키에 그대로 씁니다.
+- 422c388: ADR-0105 Amendment 1 — FRONT 가 글 주소를 다시 계산하지 않습니다. `RootTaleBlogList`·
+  `RootTaleBlogPost`(연관 글·빵부스러기)의 기본 글 링크와 `buildPostMetadata` 의 canonical 이
+  플랫폼이 저장한 정규 공개 경로 `post.path` 를 먼저 읽고, 없을 때만 종전처럼 `collections`
+  규칙 → `/blog/{slug}` 로 폴백합니다. `storedPostPath(post)` 헬퍼를 `routes` 에서 내보냅니다.
+  문서(seo·collections·blog)와 Next.js 예제가 같은 규칙으로 갱신됐습니다.
+- d303835: 공개 블로그 설정 응답 `site_profile` 에 메인 홈 전용 검색 제목·설명
+  `home_title`·`home_description` 을 additive 로 더합니다(어드민 "검색·공유 표시 >
+  메인 홈 검색 노출"). `@roottale/cms-client` 는 `siteProfile.homeTitle` /
+  `homeDescription` 으로 노출하며, null 이면 사이트 이름·사이트 설명으로 폴백하는
+  것이 계약입니다. cms-mcp 문서 `seo.md` 에 홈 `generateMetadata` 예시를 더했습니다.
+- b13696c: ADR-0105 Amendment 1 — `GET /v1/cms/public/redirects` 가 글 공개 경로 이력(post_path_history)
+  에서 옛 경로 → 현재 경로 301 을 자동으로 더합니다(`id` 접두사 `path-history:`). 운영자
+  규칙이 같은 출발 경로면 운영자 규칙이 이깁니다.
+- 86c5712: RootTale 표준 블로그 주소 `/blog/{category}/{slug}` 지원 — `RootTaleSiteConfig.categoryPath`
+  (`"direct"` 면 사이트맵 카테고리 허브가 `/blog/{category}`), collection 모드 사이트맵이 각 컬렉션의
+  `categoryPath` 를 따르며, `makeCategoryHref(basePath, categoryPath)` 를 `server`·`routes` 에서
+  내보냅니다. 문서에 표준 규칙과 라우트 배치를 적었습니다.
+- bd450bc: ADR-0105 — 콘텐츠 모델 `detail`·`category_tree` presentation 에 목록·피드 규칙 선택 필드
+  (`archives`, `feed`, `categoryPath`, `layout`)를 additive 로 더합니다. 예전 `collections`
+  설정에만 있던 규칙을 모델이 소유하며, 공개 `content-models` 응답도 값이 있을 때 함께
+  내보냅니다.
+
 ## 0.55.0
 
 ### Patch Changes

package/dist/index.js

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

@@ -284,6 +284,7 @@ tenant/site 경로, 크기, 형식을 검증한 뒤 미디어를 등록합니다
                "author_profile_id": "site-author-id",
                "author_name": "공통 작성자", "author_slug": "writer",
                "terms": [{ "taxonomy": "category", "name": "…", "slug": "…" }],
+               "pattern_slots": { "post_footer": "clinic-guide" },
                "published_at": "…" } ],
   "has_more": false,
   "next_cursor": null
@@ -294,6 +295,11 @@ tenant/site 경로, 크기, 형식을 검증한 뒤 미디어를 등록합니다
 > 미설정이면 `null`. 카테고리(`terms`)는 섹션 안의 주제로 아카이브에만 쓰입니다 →
 > [콘텐츠 유형 (Collections)](./collections.md).
 
+`pattern_slots` = 공통 블록 자리별 블록 key(자리 key → `GET /patterns` 의 `key` 또는
+`null`). 어드민 배치 규칙을 서버가 이 글의 `collection_key`에 맞춰 계산한 결과이며,
+선언된 자리(현재 `post_footer` = 글 하단)는 항상 키로 존재합니다. 글 상세·미리보기
+응답에도 같은 필드가 붙습니다 → 아래 `GET /v1/cms/public/patterns` 참고.
+
 `author_profile_id`는 사이트 공통 공개 작성자 ID입니다. 이름·사진·소개·작가 주소는
 같은 원장의 `author_name`·`author_image_url`·`author_bio`·`author_slug`로
 제공됩니다. 기존 `author_id`는 하위 호환용이므로 새 연동에서는 공개 작성자
@@ -415,8 +421,9 @@ fallback 네비를 렌더하세요 (`menus.md` 참고).
   "show_author_card": true, "toc_title": null, "toc_position": "inline",
   "author_profile_name": null, "author_profile_bio": null,
   "author_profile_image_url": null, "author_profile_image_radius": "circle",
-  "site_profile": { "site_description": null, "logo_url": null,
-    "favicon_url": null, "default_og_image_url": null },
+  "site_profile": { "site_description": null, "home_title": null,
+    "home_description": null, "logo_url": null, "favicon_url": null,
+    "default_og_image_url": null },
   "post_cta": { "title": "상담이 필요하신가요?", "description": "첫 상담은 무료입니다.",
     "button_label": "상담 문의하기", "button_href": "/contact" },
   "updated_at": null }
@@ -434,6 +441,28 @@ fallback 네비를 렌더하세요 (`menus.md` 참고).
 `generateMetadata` 에서 `post.seo?.ogImage ?? post.featured_media_url ??
 settings.siteProfile.defaultOgImageUrl` 순으로 우선합니다. `logo_url`·
 `favicon_url`·`site_description` 은 사이트 `<head>` 에 적용합니다.
+`home_title`·`home_description` 은 **메인 홈(`/`) 전용** 검색 제목·설명(어드민
+"검색·공유 표시 > 메인 홈 검색 노출")으로, `null` 이면 사이트 이름(theme
+`site_name`)·`site_description` 으로 폴백하세요(`seo.md` "메인 홈 메타데이터").
+
+## GET /v1/cms/public/patterns
+
+공통 블록(여러 글의 같은 자리에 붙는 재사용 본문) 중 **발행 상태** 목록. 어느 글의
+어느 자리에 놓을지는 글 응답의 `pattern_slots`가 이미 말해 주므로, 사이트는
+`pattern_slots[slot]` 값으로 이 목록에서 `key`를 찾아 `body_json`(Tiptap 문서)을 글
+본문과 같은 렌더러·정화 경로로 그리면 됩니다. 목록이 비었거나 요청이 실패해도 글은
+정상 열려야 합니다(블록만 생략).
+
+```json
+{ "tenant_id": "…", "site_id": "…",
+  "patterns": [ { "id": "…", "key": "clinic-guide", "name": "병원 안내",
+                  "description": "글 하단 공통 안내", "body_json": { "type": "doc", "content": [ … ] },
+                  "status": "published", "updated_at": "…" } ] }
+```
+
+- 자리 key: `post_footer`(글 하단, 본문 바로 아래). 새 자리는 문서와 함께 추가됩니다.
+- 캐시: `Cache-Control: private, max-age=10`. 어드민에서 블록·배치 규칙을 저장하면
+  `theme.updated` 웹훅이 오므로 설정류 캐시와 함께 지우세요(`revalidation-webhooks.md`).
 
 ## GET /v1/cms/public/categories
 

package/docs/blog.md

@@ -32,12 +32,18 @@ export default function BlogPage() {
       baseUrl={process.env.ROOTTALE_API_BASE}
       limit={20}
       showCategoryFilter
-      postHref={(post) => `/blog/${post.slug}`}
     />
   );
 }
 ```
 
+> **글 링크는 기본값에 맡기세요.** `postHref` 를 주지 않으면 카드·연관 글·빵부스러기의
+> 글 링크는 플랫폼이 글마다 저장해 내려주는 정규 공개 경로 `post.path`(ADR-0105)를
+> 그대로 쓰고, 없을 때(구 서버·주소 규칙 없는 유형)만 `collections` 규칙 →
+> `/blog/{slug}` 순으로 폴백합니다. `postHref={(post) => "/blog/" + post.slug}` 처럼
+> 하드코딩하면 관리자가 주소 규칙을 바꿔도 사이트가 옛 주소를 계속 그립니다 —
+> 라우트가 정말 고정인 사이트에서만 쓰세요.
+
 > **카테고리 허브 라우트(`/blog/categories/{slug}`)를 구현하세요.**
 > `showCategoryFilter` 의 카테고리 칩, `RootTaleBlogCategories`, `RootTaleBlogPost`
 > 의 `breadcrumb` 카테고리 세그먼트가 모두 기본적으로 이 경로를 링크합니다
@@ -74,6 +80,14 @@ export default function BlogPage() {
 
 ### 상세 페이지
 
+> **주소 규칙은 관리자 콘텐츠 모델(`blog`)의 presentation이 정합니다.** RootTale 표준
+> 사이트는 `/blog/{category}/{slug}`(카테고리 허브 `/blog/{category}`)이고, 이 문서의
+> 예시는 평면 `/blog/{slug}` 상세 규칙(`detail`)을 쓰는 사이트 기준입니다. 어느 쪽이든
+> 글 링크·canonical·사이트맵은 공개 API `path`(`post.path`)를 그대로 읽으면 됩니다 —
+> `content-models-and-exposures.md` "목록·피드 규칙도 모델이 소유합니다" 참고. 표준
+> 사이트의 라우트 파일 배치는 카테고리 허브 `app/blog/[category]/page.tsx`(카테고리가
+> 아니면 옛 글 주소로 보고 정본으로 301) + 글 `app/blog/[category]/[slug]/page.tsx` 입니다.
+
 ```tsx
 // app/blog/[slug]/page.tsx
 import { fetchPost } from "@roottale/cms-client/server";
@@ -406,6 +420,7 @@ export async function getPost(slug: string) {
 | `authorName` | 작성자 표시명 |
 | `authorSlug` | 작가 아카이브 slug(`/blog/author/{slug}`) — 미발급 작가는 `null` |
 | `metaJson` | 부가 메타 — `metaJson.seo`에 SEO 오버라이드 |
+| `patternSlots` | 공통 블록 자리별 블록 key(`{ post_footer: "clinic-guide" }`) — `RootTaleBlogPost`가 자동 렌더, 자체 화면은 `fetchSitePatterns` + `selectSitePatternForSlot`(`theme-and-settings.md` "공통 블록") |
 
 ### 정적 경로 사전 생성 + 메타데이터
 

package/docs/collections.md

@@ -403,6 +403,10 @@ return buildPostMetadata(post, {
 });
 ```
 
+원본 post 를 넘기면 `post.path`(플랫폼이 저장한 정규 공개 경로, ADR-0105)가 먼저
+canonical 이 되고 `collections` 는 저장 경로가 없는 글의 폴백입니다.
+`RootTaleBlogList`·`RootTaleBlogPost`(연관 글·빵부스러기)의 글 링크도 같은 순서 —
+`post.path` → `collections` 규칙 → `/blog/{slug}` — 로 정해집니다.
 자세한 동작은 `seo.md` 의 "글 메타데이터 → 공지·블로그 다중 스트림" 참고.
 
 ### revalidate

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

@@ -89,6 +89,55 @@ 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" })`의 글마다
 말단 카테고리를 정확히 하나 연결합니다. 위 예시는 다음 주소를 표현합니다.
@@ -176,9 +225,38 @@ ROOT-ADMIN 편집기 도구 모음의 **내부 링크 삽입** 버튼이 이 표
 이 글을 연결할 때 쓰는 키가 복사 버튼과 함께 표시됩니다.
 
 이 표기는 본문 `body_json`의 일반 텍스트로 저장되며 공개 API도 그대로 내보냅니다.
-해석은 고객 FRONT의 몫입니다 — 텍스트 구간에서 표기를 찾아, 현재 발행 원장의 글
-경로를 같은 규칙으로 키로 바꿔 대조한 뒤 있으면 링크로, 없으면 표시 문구만
-렌더링하세요. `code`·`pre`·이미 링크된 구간과 속성값은 변환하지 않는 것을 권장합니다.
+편집기 안에서는 칩으로 보여 주며(대상 글이 있으면 제목·발행 상태, 없으면 "아직 없는
+글"), 저장 형식은 바뀌지 않습니다.
+
+**`@roottale/cms-renderer-next` 를 쓰면 따로 구현할 것이 없습니다.** `RootTaleBlogPost`
+는 본문에 표기가 있을 때만 발행 글 경로 색인을 만들어(`fetchInternalContentPathIndex`,
+옛 slug 포함) 링크로 렌더합니다. 대상이 없는 표기는 문구만 남기고
+`<span class="rt-internal-link rt-internal-link--pending" data-rt-internal-link-pending="키">`
+로 표시하므로 배포 QA 에서 찾을 수 있습니다. 링크는 `<a class="rt-internal-link">` 입니다.
+`code`·`pre`·이미 링크된 구간과 속성값은 변환하지 않습니다.
+
+```tsx
+// 기본값 internalLinks="auto" — 필요할 때만 색인을 만든다.
+<RootTaleBlogPost apiKey={apiKey} slugOrId={slug} />
+
+// 여러 글을 한 페이지에서 그리는 등 색인을 직접 관리하려면:
+import { fetchInternalContentPathIndex, RenderTiptap } from "@roottale/cms-renderer-next/server";
+const internalLinks = await fetchInternalContentPathIndex({ apiKey, revalidate: 300 });
+<RenderTiptap doc={post.bodyJson} internalLinks={internalLinks} />
+
+// 끄려면 internalLinks={false} — 표기가 텍스트 그대로 나옵니다.
+```
+
+렌더러를 쓰지 않는 FRONT 는 직접 해석합니다 — 텍스트 구간에서 표기를 찾아, 현재 발행
+원장의 글 경로를 같은 규칙으로 키로 바꿔 대조한 뒤 있으면 링크로, 없으면 표시 문구만
+렌더링하세요(`@roottale/cms-core` 의 `findInternalContentLinkTokens`·
+`internalContentPathIndex`·`renderInternalContentLinksInHtml` 을 그대로 쓸 수 있습니다).
+
+**글의 주소는 계산하지 말고 읽으세요.** 공개 글 응답의 `path`(`@roottale/cms-client`
+에서는 `post.path`)가 플랫폼이 저장한 정규 공개 경로입니다(예 `/column/my-post`,
+상세 주소가 없는 글은 `null`). 링크·사이트맵·내부 링크 키에 이 값을 그대로 쓰면
+모델 규칙이 바뀌어도 FRONT 코드를 고칠 필요가 없습니다. 내부 링크 키는 이 경로의
+조각을 점으로 이은 값과 같습니다.
 
 **주소가 바뀐 글도 자동으로 따라가게 하려면** 공개 글 응답의 `previous_slugs`(옛 slug
 목록, 최신순 — `@roottale/cms-client`에서는 `previousSlugs`)를 함께 쓰세요. 현재 경로의

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/overview.md

@@ -41,6 +41,7 @@ RootTale CMS는 어드민(`admin.roottale.com`)에서 콘텐츠를 작성·발
 | 상담문의(리드) 접수 | `submitInquiry` — 키가 테넌트를 식별 |
 | 테마·블로그 표시·ROOT-ANALYTICS 설정 조회 | `fetchTheme` / `fetchBlogSettings` / `fetchAnalyticsConfig` |
 | 사업장 정보·메뉴·콘텐츠 유형 조회 | `fetchBusinessProfile` / `fetchMenu`·`fetchMenus` / `fetchCollections` |
+| 글 하단 공통 블록 조회 | `fetchSitePatterns` + `selectSitePatternForSlot` (`RootTaleBlogPost`는 자동) |
 
 키는 **서버 전용**입니다. 브라우저로 노출되면 안 됩니다(`NEXT_PUBLIC_*` 금지).
 `@roottale/cms-client`는 브라우저에서 import 시 의도적으로 throw 합니다.
@@ -66,5 +67,5 @@ RootTale CMS는 어드민(`admin.roottale.com`)에서 콘텐츠를 작성·발
 | `inquiries.md` | 상담문의(리드) 폼 연동 |
 | `menus.md` | 메뉴(네비게이션) — 어드민 "디자인 > 메뉴" 트리를 헤더/푸터에 렌더 |
 | `seo.md` | RSS 피드, 사이트맵, JSON-LD, 동적 OG 이미지, 공개 검색, fleet 프로브 |
-| `theme-and-settings.md` | 디자인 토큰, 블로그 표시 설정, ROOT-ANALYTICS |
+| `theme-and-settings.md` | 디자인 토큰, 블로그 표시 설정, 공통 블록(글 하단), ROOT-ANALYTICS |
 | `api-reference.md` | HTTP API 레퍼런스 (비 JS 스택용 raw 엔드포인트) |

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)
 
@@ -99,8 +105,9 @@ const menu = await fetchMenu({ apiKey, slug: "primary", tags: [MENUS_CACHE_TAG]
 | `fetchMenu` / `fetchMenus` | `MENUS_CACHE_TAG` | 디자인 > 메뉴 |
 | `fetchBlogSettings` | `BLOG_SETTINGS_CACHE_TAG` | 설정 > 블로그 |
 | `fetchCollections` | `COLLECTIONS_CACHE_TAG` | 설정 > 콘텐츠 유형 |
+| `fetchSitePatterns` | `SITE_PATTERNS_CACHE_TAG` | 콘텐츠 도구 > 공통 블록 |
 
-다섯 개를 한 벌로 묶은 `SETTINGS_CACHE_TAGS` 배열도 있습니다. 수신 라우트는
+이들을 한 벌로 묶은 `SETTINGS_CACHE_TAGS` 배열도 있습니다. 수신 라우트는
 설정 저장 신호(`theme.updated`) 한 번에 **이 목록 전체**를 지웁니다 — 무엇이
 바뀌었는지 웹훅 본문에 없기 때문이며, 쓰지 않는 이름표를 지우는 것은 아무 일도
 일어나지 않으므로 해가 없습니다.

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

@@ -22,8 +22,9 @@ description: 어드민에서 관리하는 디자인 토큰, 블로그 표시 옵
 | `fetchMenu` / `fetchMenus` | `MENUS_CACHE_TAG` |
 | `fetchBlogSettings` | `BLOG_SETTINGS_CACHE_TAG` |
 | `fetchCollections` | `COLLECTIONS_CACHE_TAG` |
+| `fetchSitePatterns` | `SITE_PATTERNS_CACHE_TAG` |
 
-다섯 개를 한 벌로 묶은 `SETTINGS_CACHE_TAGS` 배열도 내보냅니다. 이름표를 지우는
+이들을 한 벌로 묶은 `SETTINGS_CACHE_TAGS` 배열도 내보냅니다. 이름표를 지우는
 쪽(웹훅 수신 라우트) 배선은 `revalidation-webhooks.md` §1 "설정 저장"을
 따르세요 — **양쪽을 다 해야** 즉시 반영이 됩니다.
 
@@ -126,6 +127,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);
@@ -136,6 +140,48 @@ const display = resolvePostDisplay(settings, post);
 `authorProfileBio`·`authorProfileImageUrl`·`authorCardDescription`은 항상
 `null`이며 새 코드에서 사용하지 마세요.
 
+## 공통 블록 (글 하단) — fetchSitePatterns
+
+어드민 **콘텐츠 도구 > 공통 블록**에서 만든 재사용 본문(병원 안내·상담 CTA 등)을
+여러 글의 같은 자리에 붙입니다. "어느 글의 어느 자리에 어떤 블록"은 어드민의
+배치 규칙(콘텐츠 유형별)으로 정하고, **서버가 글 응답의 `patternSlots`(자리 →
+블록 key | null)로 계산해 내려주므로 사이트는 규칙을 몰라도 됩니다.** 현재
+자리는 글 하단 `post_footer` 하나입니다.
+
+- `RootTaleBlogPost`(cms-renderer-next 0.57+)는 본문 바로 아래에 자동으로 그립니다
+  — 추가 코드가 필요 없습니다.
+- 자체 글 화면을 만든 사이트는 `RootTalePostPattern` 서버 컴포넌트를 본문 아래에
+  두거나, 아래처럼 직접 조회해 글 본문과 **같은 렌더러·정화 경로**로 그립니다.
+
+```ts
+import {
+  SITE_PATTERNS_CACHE_TAG,
+  POST_FOOTER_PATTERN_SLOT,
+  fetchPost,
+  fetchSitePatterns,
+  selectSitePatternForSlot,
+} from "@roottale/cms-client/server";
+
+const post = await fetchPost({ apiKey, slugOrId });
+// post.patternSlots → { post_footer: "clinic-guide" } 처럼 자리별 블록 key
+const patterns = post?.patternSlots?.[POST_FOOTER_PATTERN_SLOT]
+  ? await fetchSitePatterns({ apiKey, tags: [SITE_PATTERNS_CACHE_TAG] }).catch(() => [])
+  : [];
+const footer = selectSitePatternForSlot(post?.patternSlots, patterns);
+// footer?.bodyJson 을 본문과 같은 Tiptap 렌더러로 그린다(없으면 아무것도 그리지 않음)
+```
+
+```tsx
+// 자체 글 화면 + 공용 렌더러 조합
+import { RootTalePostPattern } from "@roottale/cms-renderer-next/server";
+<RootTalePostPattern apiKey={apiKey} post={post} />
+```
+
+블록 목록은 `rt-site-patterns` 캐시 이름표를 가지며, 어드민에서 블록·배치 규칙을
+저장하면 `theme.updated` 웹훅이 다른 설정과 함께 지웁니다(`createRevalidateRoute`
+에 `revalidateTag` 주입 필요 — 위 "저장 즉시 반영" 참고). 미발행·삭제된 블록은
+`patternSlots` 에서 이미 `null` 이므로 사이트가 따로 걸러낼 필요가 없습니다.
+
 ## 비즈니스 프로필 (로컬 SEO) — fetchBusinessProfile
 
 어드민 **운영 > 비즈니스 프로필**에서 저장한 사업장 정보(이름·별칭·업종·

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>

package/examples/nextjs/lib/blog.ts

@@ -11,6 +11,7 @@ import {
   type ArchivePromotion,
   fetchBlogArchivePosts,
   resolveCategoryPromotion,
+  storedPostPath,
 } from "@roottale/cms-renderer-next/routes";
 
 function getApiKey(): string {
@@ -24,6 +25,11 @@ const baseUrl = process.env.ROOTTALE_API_BASE;
 export interface BlogPostMeta {
   id: string;
   slug: string;
+  /**
+   * 플랫폼이 저장한 정규 공개 경로(ADR-0105, 예 `/blog/my-post`). 링크·canonical·
+   * JSON-LD 는 이 값을 읽고, 없을 때(구 서버·주소 규칙 없는 유형)만 `/blog/{slug}` 로 폴백.
+   */
+  path: string | null;
   title: string;
   description: string;
   date: string; // publishedAt ISO
@@ -51,6 +57,7 @@ function toMeta(post: CmsPostContent): BlogPostMeta {
   return {
     id: post.id,
     slug: post.slug,
+    path: storedPostPath(post),
     title: post.title,
     description: post.excerpt ?? "",
     date: post.publishedAt ?? "",

package/package.json

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