> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getporter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> docs.json 사이드바·네비게이션 관리 스킬. 새 페이지를 사이드바에 등록하거나, 페이지 위치·그룹을 변경하거나, 그룹을 신설·개편하거나, 고아 파일을 점검할 때 사용.

# SKILL

# 사이드바/네비게이션 관리 스킬

## docs.json 구조

네비게이션은 `tabs` 최상위가 **아니라** `versions` 아래에 있다:

```json theme={null}
{
  "navigation": {
    "versions": [
      {
        "version": "Korean",
        "tabs": [
          {
            "tab": "Porter AI",
            "groups": [
              { "group": "도입 판단", "pages": ["ko/introduction", "ko/security"] }
            ]
          }
        ]
      }
    ]
  }
}
```

* `pages` 항목은 확장자 없는 경로 문자열 (`ko/introduction`).
* `pages` 안에 중첩 그룹 객체 `{ "group": "...", "pages": [...] }` 를 넣을 수 있다 (애플리케이션 플랫폼 탭의 "애플리케이션 배포 예제" > Python/Node.js 참고).

## 카테고라이징 원칙 (AGENTS.md 5원칙의 상세)

### 원칙 1: 독자 여정 순서

그룹 순서와 그룹 내 페이지 순서 모두 독자의 여정을 따른다. 탭별 여정 정의:

현재 docs.json 의 실제 그룹 구성(2026-07-28) — **여기 없는 그룹명을 지어내지 말 것**:

| 탭          | 여정 (= 그룹 순서)                                                 |
| ---------- | ------------------------------------------------------------ |
| Porter AI  | 도입 판단 → 업무 AI 활용 → 사내 지식과 시스템 연결 → 모델과 에이전트 확장 → 엔터프라이즈 거버넌스 |
| 애플리케이션 플랫폼 | Getting Started → 배포하기 → 주요 기능 → 관리하기 → 배포 예제 → CLI          |
| 운영 시스템     | Getting Started → 관리 기능 → OAuth 인증 → 컨테이너 레지스트리 → 고급 기능      |

### 원칙 2: 그룹명은 독자 과업 중심 한국어

* 명사구, 대략 2\~15자 ("내부 데이터와 지식베이스 활용" ○ / "Integrations" ✕ / "기타" ✕)
* 개발자 대상 탭의 영문 관례(Getting Started, CLI)는 예외로 허용.

### 원칙 3: 고아 파일 금지 — 아래 검사 스크립트로 확인

### 원칙 4: 기존 그룹 우선, 그룹 신설은 3기준 충족 시만

1. 배치할 페이지가 **3개 이상**이고,
2. 기존 어느 그룹의 과업 정의에도 들어맞지 않으며,
3. 여정상 위치를 한 문장으로 설명할 수 있을 때.

셋 중 하나라도 미충족이면 가장 가까운 기존 그룹에 배치한다.

## 새 페이지 배치 결정 절차

* **Q1. 주 독자는 누구인가?**
  * 도입 의사결정자 → Porter AI 탭 "도입 판단" 또는 "엔터프라이즈 거버넌스"
  * 일반 사용자 → "업무 AI 활용"
  * 개발자 → "사내 지식과 시스템 연결" 또는 애플리케이션 플랫폼 탭
  * AI 전문가 → "모델과 에이전트 확장"
  * 관리자 → "엔터프라이즈 거버넌스" 또는 운영 시스템 탭
* **Q2. 여정의 어느 단계인가?** → 탭·그룹 확정
* **Q3. 그룹 내 어디에 두는가?** → 이 페이지가 요구하는 선행 지식을 다루는 페이지 **뒤에** 배치
* **Q4. 기존 페이지와 주제가 겹치는가?** → 겹치면 신설 대신 기존 페이지 확장을 먼저 검토 (중복 부채 방지 — doc-review 스킬의 known-issues.md 참고)

## 고아 파일 검사

파일을 만들지 않는 읽기 전용 스크립트. 저장소 루트에서 실행:

```bash theme={null}
python3 - <<'EOF'
import json, glob, os
d = json.load(open('docs.json'))
reg = set()
def walk(o):
    if isinstance(o, dict):
        for p in o.get('pages', []):
            reg.add(p) if isinstance(p, str) else walk(p)
        for k in ('versions', 'tabs', 'groups'):
            walk(o.get(k, []))
    elif isinstance(o, list):
        for i in o: walk(i)
walk(d['navigation'])
files = {os.path.splitext(f)[0] for f in glob.glob('ko/**/*.mdx', recursive=True)}
files |= {os.path.splitext(f)[0] for f in glob.glob('*.mdx')}
print("고아 파일:", sorted(files - reg))
print("등록됐지만 파일 없음:", sorted(reg - files))
EOF
```

* **2026-07-28 기준 고아 28개**가 `.claude/skills/doc-review/known-issues.md` 에 기록돼 있다. 검사 결과가 28개보다 늘었다면 새 고아가 생긴 것 — 등록하거나 브랜치로 뺀다.
* 그중 `ko/ops/*` 14개는 **의도적 비공개**라 기준선에 포함돼 있다. 등록 대상으로 오해하지 말 것.
* 이 스크립트는 `ko/` 와 루트만 스캔한다. `license/license.mdx`, `snippets/snippet-intro.mdx` 는 집계에서 빠지므로 저장소 전체 `find` 기준(30개)과 2건 차이가 난다.
* "등록됐지만 파일 없음"이 나오면 사이트 빌드가 깨지므로 즉시 수정.

## 작업 후 검증

1. 위 고아 검사 스크립트 재실행 — 새 고아·누락 0 확인
2. `mintlify broken-links` — 내부 링크 검사
3. `mintlify dev` 로 사이드바 렌더링 확인 (그룹명, 순서, 아이콘)