> ## 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.

# AGENTS

# Porter AI 문서 저장소 가이드

Porter AI(기업용 AI 업무 플랫폼)의 공식 문서 사이트. Mintlify(mint 테마) 기반, 한국어 단일 버전.

## 저장소 개요

* 설정 파일은 **`docs.json`** 이다 (Mintlify 구버전 문서의 `mint.json` 에 해당).
* 3개 탭 구조:
  | 탭         | 디렉토리      | 내용                                   |
  | --------- | --------- | ------------------------------------ |
  | Porter AI | `ko/`     | 제품 소개, AI·에이전트 활용, 데이터·시스템 연결, 모델 확장 |
  | 앱 배포 플랫폼  | `ko/dev/` | 배포, CLI, 프레임워크별 예제                   |
  | 운영 시스템    | `ko/ops/` | 사용자·전역 공유 설정·OAuth 관리                |
* `snippets/` 는 Mintlify 기본 예제만 있고 실제로 사용되지 않는다.
* 이미지는 외부 URL(`https://files.cloudtype.io/...`)을 쓴다. 레거시 표기 `storage.googleapis.com/files.cloudtype.io` 가 `ko/dev/` 일부에 남아 있으나 신규 삽입에는 쓰지 않는다.
* 로고는 `logo/`(docs.json 참조), 커스텀 사이드바 아이콘은 `images/icons/` 에 둔다. `images/` 의 나머지 파일은 Mintlify 템플릿 잔재다.
* 루트 `style.css` 는 커스텀 아이콘의 active 상태 색상을 보정한다. docs.json 에 등록하지 않아도 Mintlify 가 루트 `style.css` 를 자동 로드한다.

## 로컬 개발

mintlify 는 저장소 의존성이라 전역 설치 없이 실행된다.

```bash theme={null}
npm install
npm start                    # = npx mintlify dev, 저장소 루트에서 실행
npx mintlify broken-links    # 내부 링크 검사
```

## 문서의 목적과 독자 (가장 중요)

**제1목적: 잠재 고객이 Porter AI 가 무엇이고 왜 필요한지 명확하게 인지하게 하는 것.**
기능 나열보다 "이 기능이 어떤 업무 문제를 해결하는가"를 먼저 쓴다.

독자는 3층위이며, 모든 페이지는 이 중 **주 독자 1명**을 상정하고 쓴다:

1. **도입 의사결정자** — 보안, 거버넌스, 비용, ChatGPT 대비 차별점이 관심사
2. **개발자** — MCP/REST API 연동, 앱 배포, CLI 가 관심사
3. **AI 전문가** — 모델 선택, 에이전트 구성, RAG 품질이 관심사

## 핵심 차별점

문서 전반에서 일관되게 강조하는 Porter AI 의 5대 차별점:

| 차별점      | 한 줄 표현                                                            |
| -------- | ----------------------------------------------------------------- |
| 보안       | Self-Hosting / 관리형 단독 서버 — 데이터가 조직 밖으로 나가지 않음                     |
| 모델 중립성   | Claude·OpenAI·DeepSeek·Bedrock·OpenRouter·자체 호스팅·Flowise 를 조직이 선택 |
| 에이전틱 RAG | 수백\~수만 개 사내 문서를 원문 기반으로 답변에 반영하는 지식베이스                            |
| 시스템 연결   | MCP/REST API 로 사내 업무 시스템을 AI 가 직접 조회·호출                           |
| 조직 거버넌스  | 전역 모델·데이터·Skills 관리, 사용량 모니터링·한도 — 개인용 AI 도구(ChatGPT)와의 핵심 차별     |

**규칙: 새 기능 페이지를 쓸 때 이 중 어느 차별점을 뒷받침하는지 자문하고, 페이지 도입부에서 그 차별점과 연결하라.**

## 사이드바 카테고라이징 원칙

1. **독자 여정 순서**: 그룹과 그룹 내 페이지 순서 모두 독자의 여정을 따른다.
   Porter AI 탭 = 도입 판단 → 업무 AI 활용 → 업무 에이전트 구성과 공유 → 내부 데이터와 지식베이스 활용 → 협업 툴 및 메신저 연동 → 모델 확장.
2. **그룹명은 독자의 목적/과업 중심 한국어** ("내부 데이터와 지식베이스 활용" ○ / "Integrations" ✕). 개발자 대상 탭의 Getting Started, CLI 는 관례상 예외.
3. **고아 파일 금지**: 모든 .mdx 는 docs.json 에 등록한다. 미공개 문서는 브랜치로 관리하고 master 에 미등록 파일을 남기지 않는다.
4. **새 페이지는 기존 그룹 우선 배치.** 그룹 신설은 navigation 스킬의 기준 충족 시에만.
5. docs.json 의 네비게이션 경로는 `navigation.versions[0].tabs[].groups[].pages[]` 다 (tabs 가 최상위가 아님에 주의).

→ 배치 판단 절차, 고아 검사 스크립트: `.claude/skills/navigation/`

## 문서 스타일 핵심 규칙

* **frontmatter 3필드 필수**: `title`(한국어), `description`(경어체 한 문장), `icon`(Font Awesome 이름 또는 `/images/icons/*.svg`).
  * 예외: 중첩 그룹(앱 배포 플랫폼 탭의 Python·Node.js) 하위 페이지는 그룹이 icon 을 가지므로 페이지 `icon` 을 생략한다.
* **페이지 첫 요소는 `<Card>` 리드 요약** — 기능/개념을 한 문장으로 정의.
* **페이지 유형 4종과 톤**:
  * 마케팅형(도입 판단 그룹): 문제 제기 → Porter 의 해결 방식 → 핵심 차별점 연결 서사
  * 기능 가이드형(대부분의 페이지): 정의 → 사용 방법(Steps/Frame) → 팁
  * 튜토리얼형(quickstart 류): 모든 Step 에 스크린샷, 결과 확인 포함
  * 레퍼런스형(모델 연동·CLI): 표 중심, 서사 최소화
* **컴포넌트 관례**: 스크린샷은 `<Frame><img className="block rounded-md" src="..." /></Frame>`, 순서 절차는 `<Steps>`, 부가 설명은 `<Accordion>`, 비교표는 HTML `<table>`, 콜아웃은 Tip(권장)/Info(맥락)/Note(제약)/Warning(주의).
* **한국어 표기**: 경어체("\~합니다"). 제품 개념은 원문 유지(Skills, MCP), 단 UI 라벨 인용은 화면 표기 그대로(`설정 > 스킬`).

→ 유형별 템플릿, 컴포넌트 상세 규칙, 용어집: `.claude/skills/doc-writing/`

## Git / PR 관례

* **`master` · `main` · `development` 에 commit / push / PR 금지 — PR base 로도 쓰지 않는다.** 회사 정본 브랜치다. `git status` 의 "Main branch" 표시를 신뢰하지 말 것.
* 작업은 이슈 브랜치 `{작성자}/{티켓번호}` (예: `joje/cont-254`) 에서 하고, **PR base 는 개인 통합 브랜치 `{작성자}/main`** 이다. 이 저장소의 이슈 키는 컨텐츠 팀 `CONT` 이며 `cty-` 는 과거 잔재다.
* 커밋 메시지는 **한국어 단문** (예: "비교 테이블 수정"). `feat:` 같은 prefix 없이, subject 끝에 이슈 키(`CONT-XXX`)를 붙인다.
* commit / push / PR 은 사용자가 명시적으로 지시할 때만 실행한다.

→ 이슈 생성, 브랜치 운용, 커밋 시퀀스의 **정본은 `.claude/skills/linear-issue/`** 다. 여기서 중복 서술하지 않는다.

## 작업 유형별 스킬

| 작업                        | 스킬                             |
| ------------------------- | ------------------------------ |
| 새 페이지 작성, 기존 페이지 수정       | `.claude/skills/doc-writing/`  |
| docs.json/사이드바 변경, 페이지 배치 | `.claude/skills/navigation/`   |
| 커스텀 사이드바 아이콘 적용           | `.claude/skills/custom-icons/` |
| 품질 점검, 링크·중복·고아 검사        | `.claude/skills/doc-review/`   |
| 리니어 이슈 생성, 커밋·브랜치 운용      | `.claude/skills/linear-issue/` |

페이지를 신설할 때는 doc-writing → navigation 순으로 둘 다 적용한다.
이 저장소의 규칙 수정은 항상 이 파일(AGENTS.md)에만 한다. CLAUDE.md 는 import 한 줄만 유지하고 내용을 추가하지 않는다.

## 알려진 부채 (주의)

*2026-07-28 기준. 전체 107개 .mdx 중 docs.json 등록은 77개.*

* **고아 파일 28개** (docs.json 미등록) — 새 고아를 만들지 말 것. 그중 `ko/ops/*` 14개는 **의도적 비공개**라 등록 대상이 아니다.
* **깨진 내부 링크 29건 / 13개 파일** — `157f771`·`415dc77` 의 페이지 이동·삭제 이후 정리되지 않았다. 문서를 수정할 때 `/ko/skills`, `/ko/global-*`, `/ko/dev/openclaw`, `/ko/vs-chatgpt` 같은 옛 경로를 복사하지 말 것.
* 모델 연동 페이지 6개 분산, 스텁 페이지 22개, 중복 h2 29건.
* 상세 목록과 처리 방향: `.claude/skills/doc-review/known-issues.md`