From e1d3d00b1460f6173868692f8575f230dded45fe Mon Sep 17 00:00:00 2001
From: Sin-Kang <jlc488@gmail.com>
Date: Wed, 3 Jun 2026 23:11:36 +0900
Subject: [PATCH] docs(tenancy): mark the jwt resolver as reserved (not yet
 shipped)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The deepened tenancy guide listed `resolver: jwt` as a working option, but
TenantAutoConfiguration throws for `case JWT`: it requires the (unshipped)
devslab-kit-oauth2-resource-server-starter. Only fixed / header / subdomain
actually resolve; jwt fails fast at startup.

- move jwt to the bottom of the resolver table, marked "reserved — not yet
  shipped", with a warning admonition pointing at a custom TenantResolver
  bean (the login JWT already carries a `tenant` claim to read)
- fix the yaml comment that advertised jwt as selectable

EN + KO. Pinned { #custom-resolver } on the KO heading so the new
fragment link resolves in the KO build.

Verification: mkdocs build --strict clean.
---
 docs/guides/tenancy.ko.md | 12 +++++++++---
 docs/guides/tenancy.md    | 10 ++++++++--
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/docs/guides/tenancy.ko.md b/docs/guides/tenancy.ko.md
index 55f9207..2fedbba 100644
--- a/docs/guides/tenancy.ko.md
+++ b/docs/guides/tenancy.ko.md
@@ -16,7 +16,7 @@ devslab:
   kit:
     tenant:
       mode: single            # single | multi
-      resolver: fixed         # fixed | header | jwt | subdomain
+      resolver: fixed         # fixed | header | subdomain  (jwt: 예약 — 아래 참고)
       default-tenant-id: default
 ```
 
@@ -36,8 +36,14 @@ devslab:
 | --- | --- | --- |
 | `fixed` | 항상 `default-tenant-id` | (싱글 테넌트 기본) |
 | `header` | 요청 헤더(기본 `X-Tenant-Id`) | `X-Tenant-Id: acme` |
-| `jwt` | 인증된 JWT의 클레임 | 로그인 사용자의 테넌트 |
 | `subdomain` | 요청 호스트의 서브도메인 | `acme.app.com` → `acme` |
+| `jwt` | _예약 — 아직 미출시_ | (노트 참고) |
+
+!!! warning "`jwt`는 예약됨 (아직 미출시)"
+    `resolver: jwt`를 선택하면 부팅 시 즉시 실패합니다 — 예정된
+    `devslab-kit-oauth2-resource-server-starter`를 기다리는 중입니다. 로그인 JWT는 이미 `tenant`
+    클레임을 싣고 있으니, 그때까지는 **커스텀 `TenantResolver` 빈**으로 읽으세요
+    (아래 [커스텀 리졸버](#custom-resolver)).
 
 ```yaml
 devslab:
@@ -118,7 +124,7 @@ interface InvoiceRepository extends JpaRepository<Invoice, UUID> {
 
 이게 패턴의 전부 — `single`/`multi` 동일합니다.
 
-## 커스텀 리졸버
+## 커스텀 리졸버 { #custom-resolver }
 
 내장으로 안 되는 전략(DB 조회, header-or-path, API 키 → 테넌트 매핑)이 필요하면, 자신의
 `TenantResolver` 빈을 선언하면 kit 기본이 물러납니다(모든 kit 빈이 `@ConditionalOnMissingBean`):
diff --git a/docs/guides/tenancy.md b/docs/guides/tenancy.md
index 20a5674..8864c40 100644
--- a/docs/guides/tenancy.md
+++ b/docs/guides/tenancy.md
@@ -17,7 +17,7 @@ devslab:
   kit:
     tenant:
       mode: single            # single | multi
-      resolver: fixed         # fixed | header | jwt | subdomain
+      resolver: fixed         # fixed | header | subdomain  (jwt: reserved — see below)
       default-tenant-id: default
 ```
 
@@ -37,8 +37,14 @@ In `multi` mode the **resolver** decides whose request this is:
 | --- | --- | --- |
 | `fixed` | always `default-tenant-id` | (the single-tenant default) |
 | `header` | a request header (default `X-Tenant-Id`) | `X-Tenant-Id: acme` |
-| `jwt` | a claim on the authenticated JWT | the signed-in user's tenant |
 | `subdomain` | the request host's subdomain | `acme.app.com` → `acme` |
+| `jwt` | _reserved — not yet shipped_ | (see note) |
+
+!!! warning "`jwt` is reserved (not yet shipped)"
+    Selecting `resolver: jwt` fails fast at startup — it awaits the planned
+    `devslab-kit-oauth2-resource-server-starter`. The login JWT already carries a
+    `tenant` claim, so until then resolve it from a **custom `TenantResolver` bean**
+    ([Custom resolver](#custom-resolver) below).
 
 ```yaml
 devslab: