@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ko-KR/plan-plugin.md

@@ -0,0 +1,200 @@
+---
+title: "플러그인 및 마켓플레이스 계획"
+description: "Agent-Native 계획 skills(/visual-plan, /visual-recap)와 호스팅된 계획 MCP 커넥터를 Claude 코드 또는 Codex 플러그인으로 설치하거나 범용 CLI를 사용하여 설치합니다. 업데이트 작동 방식 및 제출해야 할 사항이 있는지 여부"
+---
+
+# 플러그인 및 마켓플레이스 계획
+
+Agent-Native **Plan** 앱은 설치 가능한 하나의 번들로 제공됩니다. 단일 설치로 Plan 슬래시 명령 skills **및** 호스팅된 Plan MCP 커넥터를 모두 추가하므로 에이전트는 계획을 생성할 수 있고 skills는 이를 Plan 앱에 바로 게시할 수 있습니다.
+
+## 당신이 얻는 것 {#what-you-get}
+
+한 번의 설치로 다음을 얻을 수 있습니다:
+
+- **2개의 skills** — `/visual-plan`(표준 진입점) 및 `/visual-recap`.
+- **Plan MCP 커넥터** — `https://plan.agent-native.com`(MCP 엔드포인트 `https://plan.agent-native.com/_agent-native/mcp`, 서버 이름 `plan`)에서 호스팅된 앱에 대해 등록되었습니다.
+
+```an-diagram title="Three routes, one bundle" summary="The universal CLI, Claude Code plugin, and Codex plugin all install the same two skills plus the hosted Plan connector."
+{
+  "html": "<div class=\"diagram-routes\"><div class=\"diagram-col\"><div class=\"diagram-node\">Universal CLI<br><small class=\"diagram-muted\">skills add visual-plan</small></div><div class=\"diagram-node\">Claude Code plugin<br><small class=\"diagram-muted\">/plugin install</small></div><div class=\"diagram-node\">Codex plugin<br><small class=\"diagram-muted\">codex plugin add</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">/visual-plan</span><span class=\"diagram-pill accent\">/visual-recap</span><small class=\"diagram-muted\">two skills</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Plan MCP connector<br><small class=\"diagram-muted\">plan.agent-native.com/_agent-native/mcp</small></div></div>",
+  "css": ".diagram-routes{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-routes .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-routes .diagram-arrow{font-size:22px;line-height:1}.diagram-routes .center{display:flex;flex-direction:column;align-items:center;gap:4px;text-align:center}.diagram-routes .center .diagram-pill{margin:2px}"
+}
+```
+
+기본적으로 skills는 모두 호스팅된 계획 앱에 게시하며 다음을 통해 계획을 생성합니다.
+MCP 커넥터를 검토하고 검토할 링크 또는 인라인 계획을 건네줍니다. 그들은 절대로 버리지 않습니다
+인라인 Markdown/ASCII 계획을 결과물로 채팅에 포함합니다. 계획 도구인 경우
+`needs auth`, `Unauthorized` 또는 `Session terminated`를 반환하고 재인증하세요
+인라인 출력으로 돌아가는 대신 커넥터를 사용하세요. 액세스 토큰은
+오래 지속되므로(기본값은 30일, 슬라이딩 365일 새로 고침) 이러한 경우는 거의 발생하지 않습니다.
+이런 경우 간단한 수정 사항은 다음과 같습니다.
+
+```bash
+npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex
+```
+
+`reconnect`는 선택한 로컬에 대해 URL로 커넥터를 찾아 새로 고칩니다.
+클라이언트 — 재설치가 필요하지 않습니다. 다시 연결한 후 새 Codex 스레드를 시작하여
+도구 레지스트리가 다시 로드됩니다. Claude 코드에서는 `/mcp` →
+**인증/재연결** 또는 `--client claude-code`와 동일한 명령.
+
+명시적인 **로컬 파일 개인 정보 보호 모드**는 예외입니다. DB를 요청하지 않을 때
+`AGENT_NATIVE_PLANS_MODE=local-files`를 쓰거나 설정하면 skills는 호출하면 안 됩니다
+계획 MCP 커넥터. 그들은 `plans/<slug>/plan.mdx`와 선택사항을 씁니다
+`canvas.mdx`, `prototype.mdx` 및 `.plan-state.json`를 사용한 후 다음을 사용하여 로컬로 미리 봅니다.
+
+```bash
+npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --open
+```
+
+이것은 작은 로컬 호스트 브리지를 시작하고 로컬에 대한 UI 계획을 엽니다
+폴더. (`plan local preview`는 대신 로컬 계획 개발 서버 경로를 실행하고
+`plan local preview --out preview.html`는 다음을 작성하는 레거시 탈출구입니다.
+독립형 정적 HTML 파일. `plan serve`는
+`plan local serve`.)
+
+알아둘 만한 몇 가지 로컬 파일 모드 문제:
+
+- **Chromium 브라우저를 사용하세요.** Safari는 다음에서 호스팅된 HTTPS 계획 페이지를 차단합니다.
+  `http://127.0.0.1` 로컬 호스트 브리지 읽기(혼합 콘텐츠/개인
+  네트워크), 페이지가 "계획 로드 중"에서 멈춥니다. macOS `--open`에서는 이미
+  Chrome/Chromium/Edge/Brave를 선호합니다. 어쨌든 Safari가 열리면 인쇄된 파일을 다시 엽니다
+  Chromium 브라우저의 URL.
+- **제공된 URL는 `plans/<slug>/.plan-url`에 기록됩니다**(다음으로 재정의됨
+  `--url-file`). 백그라운드 또는 헤드리스 에이전트는 대신 해당 파일을 읽을 수 있습니다.
+  장기 실행 `serve` stdout을 스크래핑합니다. 로컬 토큰 파일로 취급하고
+  커밋하지 마세요.
+- **사용 가능한 브라우저가 없을 때 헤드리스로 확인**:
+  `npx @agent-native/core@latest plan local verify --dir plans/<slug>`가 시작됩니다
+  브리지, 개인 네트워크 사전 비행 및 JSON 페이로드 확인, 인쇄
+  진단하고 실패 시 0이 아닌 값으로 종료합니다. 사람의 눈이 필요하지 않습니다.
+- **먼저 `plan local check`를 실행합니다.** 계획에 대해 MDX를 검증합니다
+  렌더러의 블록 스키마(`checklist` 항목과 같은 필수 필드 포함
+  `id`/`label` 및 `question-form` 질문 `id`/`title`/`mode`), 작성
+  고착된 로더가 아닌 브라우저 핸드오프 전에 실수가 표면화됩니다.
+
+현재 저장소에 있는 폴더의 경우 직접 로컬 경로에 `?path=...`가 포함되므로
+로컬 플랜 앱은 브라우저 편집 내용을 repo 폴더에 계속 저장할 수 있습니다. 계획
+앱은 `agent-native.json`의 `apps.plan.roots[0].path`를 기본 장소로 사용합니다
+승격된 지역 계획을 저장하려면 `plans/`로 대체합니다.
+
+이렇게 하면 계획 내용이 Agent-Native 계획 데이터베이스에 포함되지 않습니다. 호스팅된 공유,
+댓글, 스크린샷, 계획 내역은 귀하가 명시적으로 설명할 때까지 사용할 수 없습니다.
+나중에 게시하세요.
+
+```an-diagram title="Hosted vs. local-files mode" summary="By default skills publish through the connector; local-files mode writes MDX to disk and previews via a localhost bridge instead."
+{
+  "html": "<div class=\"diagram-modes\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Default · hosted</span><strong>Publish to the Plan app</strong><small class=\"diagram-muted\">MCP connector &rarr; hosted DB &rarr; share links, comments, history, screenshots</small></div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">Local-files privacy</span><strong>Write MDX to disk</strong><small class=\"diagram-muted\">plan.mdx + canvas.mdx + prototype.mdx &rarr; localhost bridge &rarr; hosted Plan UI reads local source. No DB writes until <code>publish-visual-plan</code>.</small></div></div>",
+  "css": ".diagram-modes{display:flex;gap:14px;flex-wrap:wrap}.diagram-modes .diagram-card{flex:1 1 260px;display:flex;flex-direction:column;gap:6px;padding:16px 18px}"
+}
+```
+
+Agent Native 데스크탑에는 호스팅 계획에 대한 별도의 로컬 파일 동기화 경로가 있습니다:
+데스크톱 앱은 호스팅된 계획을 로컬 MDX 파일에 미러링하고 편집 내용을 다시 가져올 수 있습니다.
+Plan 앱을 복제하거나 CLI를 실행하지 않고. 해당 워크플로우는 호스팅된
+데이터베이스를 진실의 소스로 계획합니다. 목표가 있을 때 로컬 파일 개인정보 보호 모드를 사용하세요
+계획 DB 쓰기가 없습니다.
+
+> 플러그인(`agent-native-visual-plans`)은 앱 ID `visual-plans`를 전달하므로 Claude 코드 플러그인 이름과 Codex 플러그인 이름이 모두 `agent-native-visual-plans`입니다. Plan 앱의 표시 이름은 "Agent-Native Plan"입니다.
+
+## 경로 설치 {#install}
+
+세 가지 방법이 있습니다. **범용 CLI 경로**는 기본적으로 권장되는 경로입니다. 왜냐하면 skills를 설치하고\*\* 하나의 흐름에서 호스팅, 로컬 파일 또는 자체 호스팅 모드를 선택할 수 있기 때문입니다. 플러그인 경로는 최고 수준의 플러그인/마켓플레이스 시스템을 갖춘 호스트를 위한 것이며 기본적으로 호스팅된 계획을 사용합니다.
+
+### 범용 기술 경로(모든 MCP 호스트) {#universal}
+
+Claude Code, Codex, Cursor, Cline, Goose, ChatGPT 맞춤형 MCP 앱, Claude Cowork 및 기타 MCP 호환 등 모든 호스트에서 작동합니다. Agent-Native CLI는 skills를 모두 설치하고 호스팅된 MCP 계획 커넥터를 등록하며 **동일한 단계에서 선택한 로컬 클라이언트에 대한 인증을 실행**하므로 첫 번째 도구 호출이 OAuth 벽에 부딪히지 않습니다.
+
+```bash
+npx @agent-native/core@latest skills add visual-plan
+```
+
+이렇게 하면 `visual-plan`와 동반 `visual-recap` 기술이 설치되고 `plan` 커넥터가 등록된 다음 인증이 실행됩니다(호스팅/계정 지원 공유에 대한 OAuth 프롬프트). 유용한 플래그:
+
+- `--client codex|claude-code|claude-code-cli|cowork|all` — MCP 구성을 작성할 로컬 에이전트(기본값 `all`).
+- `--no-connect` — 인증 없이 커넥터를 등록합니다. 나중에 `npx @agent-native/core@latest connect https://plan.agent-native.com --client all`를 실행하거나 더 좁은 `--client`를 선택하세요.
+- `--mode hosted|local-files|self-hosted` — 호스팅된 공유, 모든 로컬 MDX 파일 또는 자체 요금제 앱을 선택하세요.
+- `--mcp-url <url>` — 호스트된 기본값 대신 사용자 지정 원본(ngrok 터널, 로컬 개발 서버 또는 자체 호스팅 배포)에서 커넥터를 가리킵니다.
+- `--with-github-action` — PR 시각적 요약 GitHub 작업도 작성합니다([PR Visual Recap](/docs/pr-visual-recap) 참조).
+
+대화형 설치는 워크플로가 없을 때 PR 시각적 요약 작업도 제공합니다.
+현재. 스킬 설정 중에 추가하려면 예라고 말하거나 나중에 위 명령을 실행하세요
+`--with-github-action`로. 워크플로가 작성된 후 다음을 실행하세요.
+
+```bash
+npx @agent-native/core@latest recap setup
+npx @agent-native/core@latest recap doctor
+```
+
+`recap setup`는 가능한 경우 GitHub 작업 비밀과 변수를 구성합니다.
+및 `recap doctor`는 워크플로, 로컬 게시 토큰, GitHub 저장소를 확인합니다.
+액세스 및 필수 Actions 구성. 설치가 완료된 후 다시 시작하거나
+에이전트 클라이언트를 다시 로드하여 새 skills 및 도구를 로드한 후 실행
+`/visual-plan`.
+
+> 참고: 베어 `npx skills@latest add BuilderIO/agent-native --skill visual-plan`(Vercel/open Skills CLI)는 **지침만** 설치하며 MCP 커넥터를 등록하지 않습니다. 커넥터도 배선하려면 위의 Agent-Native CLI를 사용하세요.
+
+### Claude 코드(플러그인) {#claude-code}
+
+공개 `BuilderIO/agent-native` 저장소는 그 자체로 Claude 코드 플러그인 마켓플레이스이므로 빌드 단계 없이 직접 추가할 수 있습니다. Claude 내부 코드:
+
+```text
+/plugin marketplace add BuilderIO/agent-native
+/plugin install agent-native-visual-plans@agent-native-apps
+/reload-plugins
+/mcp        # authenticate the Plan connector (one OAuth approval)
+```
+
+`/plugin install`는 계획 skills와 **URL 전용** MCP 구성을 모두 추가합니다(패키지에 비밀이 없음). `/mcp` → **인증**을 통해 OAuth 핸드셰이크가 완료됩니다. 로컬 파일이나 자체 호스팅 모드를 원할 때는 대신 범용 CLI 경로를 사용하세요.
+
+> 마켓플레이스 카탈로그 이름은 `agent-native-apps`이고 Plan 플러그인은 `agent-native-visual-plans`이므로 설치 대상은 항상 `agent-native-visual-plans@agent-native-apps`입니다.
+
+### Codex(플러그인) {#codex}
+
+동일한 저장소는 Codex 플러그인 마켓플레이스입니다. 이를 추가하고 플러그인을 설치한 다음 커넥터를 인증하세요.
+
+```bash
+codex plugin marketplace add BuilderIO/agent-native
+codex plugin add agent-native-visual-plans@agent-native-apps
+codex mcp login plan   # OAuth in the browser
+```
+
+설치 후 **새 Codex 스레드를 시작**하여 skills 및 MCP 도구가 세션에 로드되도록 합니다. 플러그인은 URL 전용 커넥터(`[mcp_servers.plan]` → `https://plan.agent-native.com/_agent-native/mcp`)를 제공합니다. `codex mcp login plan`는 OAuth 흐름을 실행합니다. 위의 범용 CLI 경로는 함께 설치하고 인증하는 하나의 명령을 선호하거나 로컬 파일 또는 자체 호스팅 모드를 원하는 경우 Codex(`npx @agent-native/core@latest skills add visual-plan --client codex`)에도 작동합니다.
+
+> **이전 설치:** 구성에 여전히 동일한 URL를 가리키는 `agent-native-plans` 항목이 있거나 Codex에 대해 `npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`를 실행하거나 대상 `--client`와 동일한 명령을 실행하는 경우 이를 표준 `plan` 이름으로 통합합니다.
+
+## 업데이트 {#updates}
+
+플러그인은 자동 업데이트 경로를 지정합니다. 일상적인 기술 변경을 위해 마켓플레이스를 다시 포장하거나 다시 추가하지 않습니다.
+
+- **Claude 코드** — 마켓플레이스 항목은 `autoUpdate: true`를 설정하고 플러그인은 커밋-SHA 버전 관리를 사용하므로 Claude 코드는 시작 시 저장소에서 새 버전을 가져옵니다. 활성화하려면 `/reload-plugins`를 실행하세요. 저장소의 기본 분기에 대한 모든 푸시는 설치된 사용자에게 자동으로 도달합니다.
+- **Codex** — `version` 플러그인은 번들로 제공되는 skills 및 MCP 엔드포인트(예: `1.0.0+codex.<hash>`)의 콘텐츠 해시를 포함하므로 기술이나 엔드포인트가 변경되면 새 버전이 생성됩니다. Codex의 시작 자동 업그레이드는 구성된 git 마켓플레이스를 자체적으로 다시 설치합니다. 변경 사항을 적용하려면 **새 스레드를 시작**하세요. 일상적인 업데이트에는 수동 `codex plugin marketplace upgrade`가 필요하지 않습니다.
+- **범용 CLI 경로** — 복사된 스킬 폴더를 확인하려면 `npx @agent-native/core@latest skills status visual-plan`를 실행하고, 제자리에서 새로 고치려면 `npx @agent-native/core@latest skills update visual-plan`를 실행하세요. 커넥터를 다시 등록/인증하려는 경우에도 `skills add visual-plan`를 다시 실행하면 계속 작동합니다. `@latest`는 항상 게시된 `@agent-native/core` 패키지에서 현재 skills를 가져옵니다.
+
+커넥터는 **호스팅** 앱을 가리키므로 Plan 앱의 actions 및 라이브 도구 표면은 설치 시점에 관계없이 항상 배포된 버전을 반영합니다. 번들로 제공되는 기술 지침만 위의 업데이트 메커니즘을 따릅니다.
+
+> **유지관리자:** 마켓플레이스 번들(`.claude-plugin/`, `.agents/plugins/`)은 `pnpm sync:plan-marketplace`의 정식 계획 skills에서 생성되고 `pnpm guard:plan-marketplace`의 CI에서 확인되므로 게시된 마켓플레이스는 항상 정식 skills와 일치합니다. 스킬을 편집하고 `pnpm sync:plan-marketplace`를 실행한 후 커밋하세요.
+
+## 제출해야 할 사항이 있나요? {#submission}
+
+**이것을 배포하거나 설치하는 데 제출이나 검토가 필요하지 않습니다.** `BuilderIO/agent-native`는 자체 호스팅 공개 Git 마켓플레이스이므로 사용자는 **Claude 코드 및 Codex**에서 위 명령을 사용하여 직접 추가할 수 있으며 신청이나 승인이 필요하지 않습니다. 범용 CLI 경로에는 마켓플레이스가 전혀 필요하지 않습니다.
+
+공개 목록을 원하는 경우 선택적 검색 가능성:
+
+- **Claude 코드**에는 등록을 위해 _선택적으로_ 제출할 수 있는 커뮤니티 마켓플레이스가 있습니다(제출과 자동 검토). Anthropic이 큐레이트한 공식 마켓플레이스는 Anthropic의 재량에 따라 등록되며, 공개된 셀프 서비스 애플리케이션은 없습니다. 위의 설치 명령을 사용할 필요도 없습니다.
+- **Codex**에는 OpenAI 선별 플러그인 카탈로그(셀프 서비스 제출이 아닌 파트너십으로 제공되는 폐쇄형 허용 목록)가 있습니다. 자체 호스팅 Git 마켓플레이스 및 CLI 경로는 제출할 필요가 없습니다.
+
+간단히 말하면, 자체 호스팅/공용 Git 마켓플레이스로 제공하면 사용자가 직접 설치할 수 있습니다. 검색용으로 나열하려는 경우에만 선별된 카탈로그에 제출하세요.
+
+## 플러그인 대 스킬 {#plugin-vs-skill}
+
+**스킬**은 작업이 일치할 때 에이전트가 읽는 단일 `SKILL.md` 지침 파일입니다. **플러그인**(Claude 코드 마켓플레이스 플러그인 또는 Codex 플러그인)은 하나 이상의 skills **추가** MCP 커넥터 및 메타데이터를 번들로 제공하는 패키지이므로 호스트는 모든 것을 한 단계에서 설치할 수 있습니다.
+
+내부적으로 세 가지 경로는 모두 `npx @agent-native/core@latest app-skill` CLI에 의해 동일한 소스에서 생성됩니다. `app-skill pack`는 마켓플레이스/플러그인 어댑터를 구축하고 `skills add`는 MCP 커넥터를 등록하고 인증하는 친숙한 1단계 설치 프로그램입니다. 앱 스킬 매니페스트 형식은 [Skills Guide](/docs/skills-guide)를 참조하고 MCP 호스트와 `npx @agent-native/core@latest connect` 흐름을 연결하려면 [External Agents](/docs/external-agents)를 참조하세요.
+
+## 다음 단계 {#whats-next}
+
+- [**Visual Plans**](/docs/template-plan) — skills의 기능 및 사용 방법
+- [**PR Visual Recap**](/docs/pr-visual-recap) — 풀 요청이 있을 때마다 자동으로 `/visual-recap`를 실행합니다.
+- [**Skills Guide**](/docs/skills-guide) — 앱 지원 skills 및 매니페스트 형식
+- [**External Agents**](/docs/external-agents) — MCP 호스트 및 왕복 아티팩트 연결

package/docs/content/locales/ko-KR/pr-visual-recap.md

@@ -0,0 +1,384 @@
+---
+title: "홍보 영상 요약"
+description: "모든 PR에서 저장소의 시각적 요약 기술을 실행하는 GitHub 액션입니다. LLM 코딩 에이전트는 차이점을 읽고, 대화형 요약 계획을 게시하고, 정보 확인을 표시하고, 인라인 스크린샷과 함께 끈적한 PR 댓글을 게시합니다. 정보 제공 및 비차단."
+---
+
+# 홍보 영상 요약
+
+PR Visual Recap은 모든 끌어오기 요청을 **시각적 코드 검토**로 전환하는 GitHub 작업입니다. 푸시할 때마다 LLM 코딩 에이전트는 PR diff에 대해 최신 번들 [`visual-recap`](/docs/template-plan) 기술(또는 `VISUAL_RECAP_SKILL_SOURCE=repo`인 경우 저장소의 커밋된 복사본)을 실행하고, 호스팅된 Plans 앱에 구조화된 요약 계획을 게시하고, 실행되는 동안 정보용 `Visual Recap` 검사를 표시하고, 댓글에 바로 포함된 **인라인 스크린샷**과 함께 대화형 계획에 연결되는 **끈끈한 PR 댓글** 하나를 업서트합니다.
+
+이것은 결정적 diff 렌더러가 아닙니다. 이 작업은 변경 사항을 읽고, 중요한 사항을 결정하고, Plans MCP 도구 `create-visual-recap`(`/visual-recap` 슬래시 명령에서 사용하는 것과 동일한 도구)를 호출하여 요약을 작성하는 실제 코딩 에이전트(기본적으로 Claude 코드 CLI 또는 OpenAI Codex CLI)를 호출합니다. 원시 차이점의 벽 대신 변경 사항에 대한 높은 고도의 스키마/API/전후 보기를 얻을 수 있습니다.
+
+요약은 **정보 제공 및 비차단**입니다. 검토자가 생성이 진행 중임을 알 수 있도록 확인 행을 생성하지만 필수 확인은 아니며 PR을 차단하지 않으며 실제 차이점을 읽는 것을 대체하지 않습니다. 고정 댓글은 승인을 위한 것이 아니라 검토를 위한 것입니다.
+
+## 무엇을 하는가
+
+각 PR 푸시 시 워크플로는 다음과 같습니다.
+
+1. PR 베이스와 머리 사이의 경계 차이를 수집합니다.
+2. `Visual recap in progress`를 사용하여 정보용 `Visual Recap` GitHub 검사를 생성합니다.
+3. 해당 diff에 대해 구성된 코딩 에이전트를 실행합니다. 에이전트는 번들로 제공되는 `visual-recap` 기술 지침(또는 저장소에 고정된 사본)을 읽고 요약을 작성하여 `create-visual-recap`로 게시합니다.
+4. 에이전트가 `recap-url.txt`에 쓴 게시된 계획 URL를 읽습니다.
+5. 헤드리스 Chrome에서 URL를 열고 밝은 모드와 어두운 모드에서 렌더링된 계획의 스크린샷을 찍습니다.
+6. Plans 앱의 서명된 공개 이미지 경로에 PNG를 업로드합니다.
+7. 대화형 요약 링크 옆에 `<picture>` 요소(GitHub의 위장 이미지 프록시를 통해 제공됨)와 함께 스크린샷 **인라인**을 삽입하는 단일 고정 PR 댓글을 업로드합니다.
+8. `Visual Recap` 검사를 성공, 건너뛰기 또는 중립으로 완료합니다.
+
+```an-diagram title="What happens on each PR push" summary="A bounded diff feeds a real coding agent, which authors a recap; the workflow screenshots it and upserts one sticky comment."
+{
+  "html": "<div class=\"diagram-recap\"><div class=\"diagram-node\">PR push<br><small class=\"diagram-muted\">bounded base&hellip;head diff</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Coding agent<br><small class=\"diagram-muted\">Claude Code / Codex reads diff</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">create-visual-recap</span><small class=\"diagram-muted\">publishes recap plan</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Headless Chrome<br><small class=\"diagram-muted\">light + dark screenshots</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">One sticky PR comment<br><small class=\"diagram-muted\">inline screenshot + plan link</small></div></div><div class=\"diagram-foot diagram-muted\">Plus an informational <span class=\"diagram-pill\">Visual Recap</span> check &mdash; non-blocking, never required.</div>",
+  "css": ".diagram-recap{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.diagram-recap .diagram-arrow{font-size:20px;line-height:1}.diagram-recap .center{display:flex;flex-direction:column;align-items:center;gap:4px;text-align:center}.diagram-recap .diagram-foot{flex-basis:100%;margin-top:10px;font-size:13px}"
+}
+```
+
+다시 푸시하면 동일한 계획과 동일한 고정 댓글이 업데이트됩니다. 고아 계획이나 댓글 스팸이 없습니다.
+
+## 설치
+
+대화식으로 Plans를 설치하면 Agent-Native CLI가 추가 여부를 묻습니다.
+자동 PR 시각적 요약. GitHub Action을 작성하려면 '예'라고 말하거나 추가하세요.
+언제든지 명시적으로:
+
+```bash
+npx @agent-native/core@latest skills add visual-plan --with-github-action
+```
+
+이렇게 하면 `visual-plan` 스킬(액션이 실행하는 `visual-recap` 스킬 포함)이 설치되고 저장소에 `.github/workflows/pr-visual-recap.yml`가 기록됩니다. 워크플로는 `gate`, `collect-diff`, `block-reference`, `scan`, `build-prompt`, `publish`, `shot`, `comment`, `check`를 포함하여 `npx @agent-native/core@latest recap <subcommand>`를 통해 **게시된 CLI 하위 명령**을 호출합니다. `usage` — 따라서 저장소에 도우미 스크립트로 복사되는 것은 없습니다. `setup` 및 `doctor`는 로컬에서 실행하는 대화형 도우미입니다. `gate`는 모든 요약 전에 워크플로가 실행되는 보안 게이트 단계입니다.
+
+그런 다음 안내식 설정 도우미를 실행하세요.
+
+```bash
+npx @agent-native/core@latest recap setup
+npx @agent-native/core@latest recap doctor
+```
+
+`recap setup`는 작업 흐름을 새로 고치고 `gh`를 사용하여 GitHub Actions를 설정합니다.
+env 또는 로컬 계획에서 값을 사용할 수 있는 경우 비밀/변수
+게시 토큰 저장 및 인쇄할 수 없는 모든 명령에 대해 정확히 누락된 명령 인쇄
+세트. 비밀 값은 명령 인수가 아닌 stdin을 통해 `gh`로 전송됩니다. 커밋
+생성된 워크플로 파일을 열고 PR을 열어 실행을 확인하세요.
+
+기본적으로 워크플로는 최신 번들에서 에이전트 프롬프트를 작성합니다.
+형제를 포함한 `@agent-native/core@latest`의 `visual-recap` 지침
+스킬과 함께 제공되는 참조 파일입니다. 저장소가 의도적으로 사용자 정의되고
+커밋된 `visual-recap` 폴더를 고정하고 저장소 변수를 설정합니다.
+`VISUAL_RECAP_SKILL_SOURCE=repo`.
+
+## 백엔드 선택
+
+`VISUAL_RECAP_AGENT` 저장소 변수를 사용하여 기술을 실행하는 코딩 에이전트를 선택하세요:
+
+| `VISUAL_RECAP_AGENT` | 코딩 에이전트    | 필수 API 키         |
+| -------------------- | ---------------- | ------------------- |
+| `claude` _(기본값)_  | Claude 코드 CLI  | `ANTHROPIC_API_KEY` |
+| `codex`              | OpenAI Codex CLI | `OPENAI_API_KEY`    |
+
+변수가 설정되지 않은 경우 작업은 `claude`를 사용합니다.
+
+## 모델 및 추론
+
+백엔드 외에도 두 개의 저장소 변수가 에이전트 실행 *방법*을 조정합니다.
+
+- **`VISUAL_RECAP_MODEL`**는 CLI(`--model`)에 전달된 모델을 고정합니다. 예를 들어 Codex의 경우 `gpt-5.5` 또는 Claude 모델 ID입니다. CLI 자체 기본 모델을 사용하려면 설정하지 않은 상태로 두세요.
+- **`VISUAL_RECAP_REASONING`**는 추론 깊이를 `none`, `minimal`, `low`, `medium`, `high` 또는 `xhigh`로 설정합니다. 이는 Codex 백엔드에 적용됩니다. Claude의 추론은 모델 중심이므로 이 변수는 무시됩니다.
+- **`VISUAL_RECAP_SKILL_SOURCE`**는 프롬프트 최신성을 제어합니다. `auto`/unset은 최신 번들 기술 지침을 사용하고 `repo`는 커밋된 저장소 로컬 `visual-recap` 기술 폴더에 고정합니다.
+
+예를 들어 GPT-5.5를 사용하여 Codex에 대한 요약을 실행하려면 저장소 변수 `VISUAL_RECAP_AGENT=codex`, `VISUAL_RECAP_MODEL=gpt-5.5` 및 `VISUAL_RECAP_REASONING=high`를 설정하세요.
+
+## 비밀 및 변수
+
+이를 저장소의 **설정 → 비밀 및 변수 → Actions**에서 설정하세요.
+
+### 비밀번호(2개만 필요)
+
+| 비밀                | 목적                                                                                                                     |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `PLAN_RECAP_TOKEN`  | `npx @agent-native/core@latest connect`가 발행한 취소 가능한 토큰입니다. 요약 계획 게시 및 스크린샷 업로드를 승인합니다. |
+| `ANTHROPIC_API_KEY` | 기본 Claude 코드 백엔드에 대한 LLM 키입니다.                                                                             |
+
+**팀: 조직 서비스 토큰을 사용합니다.** 개인 토큰은 개인에게 귀속됩니다.
+만든 사람 - 조직을 떠나거나 토큰을 취소하면 모든 저장소는
+해당 비밀은 401로 실패하기 시작하고 CI 생성 계획은 그 소유입니다
+팀 대신 개인. 조직 서비스 토큰은 귀하의 소유입니다
+**조직**: 서비스 주체(`svc-<name>@service.<orgId>`) 역할을 합니다.
+개인이 떠나도 살아남고 게시된 요약은 조직에서 볼 수 있으며
+모든 조직 소유자 또는 관리자가 이를 나열하거나 취소할 수 있습니다. 민트 1(조직 소유자/관리자 전용):
+
+```bash
+npx @agent-native/core@latest connect https://plan.agent-native.com --service-token pr-recap
+```
+
+이 명령은 브라우저에서 사용자를 인증한 다음 서비스 토큰을 인쇄합니다.
+정확히 한 번 — `PLAN_RECAP_TOKEN` 비밀로 저장하세요. 나중에
+`list-org-service-tokens` 및 `revoke-org-service-token` actions
+계획 앱.
+
+**솔로: 개인 토큰은 여전히 작동합니다.** `npx @agent-native/core@latest connect`로 발행하세요
+Plans 앱에 반대합니다. 호스팅된 앱의 경우 로컬
+`npx @agent-native/core@latest recap setup`가 읽을 수 있는 게시 토큰 파일:
+
+```bash
+npx @agent-native/core@latest connect https://plan.agent-native.com --client codex
+npx @agent-native/core@latest recap setup
+```
+
+수동 설정을 선호하는 경우 토큰을 GitHub 비밀번호에 붙여넣으세요. 사용
+`plan_recap_xxxxxxxxxxxxxxxx`와 같은 자리 표시자는 예시일 뿐입니다. 절대 커밋하지 마세요
+실제 토큰.
+
+### 선택 사항(기본값을 변경하는 경우에만)
+
+| 비밀/변수                | 기본값                          | 필요할 때                                                                                                                                           |
+| ------------------------ | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OPENAI_API_KEY`         | —                               | 비밀. 대신 Codex로 요약을 실행하려면 `VISUAL_RECAP_AGENT=codex`와 함께 설정하세요.                                                                  |
+| `VISUAL_RECAP_AGENT`     | `claude`                        | 변수. 코딩 에이전트 백엔드(`claude` 또는 `codex`)를 선택합니다.                                                                                     |
+| `VISUAL_RECAP_MODEL`     | 각 CLI의 기본값                 | 변수입니다. 모델을 고정합니다. Codex의 경우 `gpt-5.5` 또는 Claude 모델 ID입니다. Unset은 CLI 자체 기본값을 사용합니다.                              |
+| `VISUAL_RECAP_REASONING` | 각 모델의 기본값                | 변수입니다. 추론 깊이: `none`, `minimal`, `low`, `medium`, `high` 또는 `xhigh`. Codex 백엔드에 적용됩니다.                                          |
+| `RECAP_CLI_VERSION`      | `latest`                        | 변수입니다. 워크플로가 설치하는 `@agent-native/core` CLI 버전을 고정합니다. `1.5.0`. [Version pinning](#version-pinning-copy-variant)를 참조하세요. |
+| `PLAN_RECAP_APP_URL`     | `https://plan.agent-native.com` | 비밀. 다른 출처에서 Plans 앱을 자체 호스팅하는 경우에만 해당됩니다.                                                                                 |
+
+워크플로는 도우미 CLI(이 모노레포 내의 로컬 소스, 다른 곳에 게시된 `@agent-native/core`)를 호출하는 방법을 자동으로 감지하므로 설정할 `RECAP_CLI` 변수가 없습니다.
+
+## 댓글의 인라인 스크린샷
+
+에이전트가 요약을 게시한 후 워크플로는 라이트 모드와 다크 모드 모두에서 헤드리스 Chrome에서 렌더링된 계획의 스크린샷을 찍고 PNG를 Plans 앱의 서명된 공개 이미지 경로에 업로드합니다. 고정 PR 댓글에는 해당 스크린샷을 `<picture>` 요소와 함께 **인라인** 삽입합니다. GitHub는 위장 프록시를 통해 해당 스크린샷을 다시 제공하므로 리뷰어는 아무것도 열지 않고도 댓글에서 직접 GitHub 테마와 일치하는 미리보기를 볼 수 있습니다. 탐색하고, 댓글을 달고, 주석을 달고 싶을 때 전체 대화형 계획에 대한 링크가 바로 옆에 있습니다.
+
+## 포크 PR
+
+### 기본 동작(조치 필요 없음)
+
+기본 `pr-visual-recap.yml` 워크플로는 `pull_request_target`가 **아님** 일반 `pull_request` 트리거에서 실행됩니다. 따라서 포크 PR은 **저장소 비밀에 대한 액세스 권한 없음**으로 실행되므로 워크플로는 `PLAN_RECAP_TOKEN`를 찾지 않고 완전히 무작동(no-ops)을 찾습니다. 즉, 게시 실패나 자격 증명 노출이 없습니다. 요약은 비밀을 사용할 수 있는 동일한 저장소에 있는 브랜치의 PR에 대해 자동으로 실행됩니다.
+
+이는 또한 비밀이 존재하기 **전에** 워크플로 파일을 병합할 수 있음을 의미합니다. 토큰이 구성되지 않으면 비밀을 설정할 때까지 모든 실행이 조용하게 작동하지 않습니다. `gate` 단계에서는 PR 초안과 봇이 작성한 PR도 자동으로 건너뛰므로 두 트리거 요약 모두 기본적으로 실행되지 않습니다.
+
+### 라벨 게이트 포크 워크플로 선택
+
+포크 PR에 대한 요약을 생성하려는 경우 두 번째 워크플로 파일인 `.github/workflows/pr-visual-recap-fork.yml`를 사용할 수 있습니다. `pull_request_target`(base-repo 비밀로 실행)를 사용하지만 포크 코드를 체크아웃하거나 실행하지 않습니다. GitHub 작성자 협회 `OWNER`, `MEMBER` 또는 `COLLABORATOR`가 있는 신뢰할 수 있는 포크 작성자가 자동으로 실행됩니다. 외부 포크 PR에는 요약 에이전트가 실행되기 전에 새로운 `recap` 라벨 이벤트를 통해 명시적인 **헤드당 관리자 옵트인**이 필요합니다.
+
+설치하려면 [BuilderIO/agent-native](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/pr-visual-recap-fork.yml)의 파일을 기존 `pr-visual-recap.yml`와 함께 저장소의 `.github/workflows/` 디렉터리에 복사하세요. 동일한 비밀(`PLAN_RECAP_TOKEN`, `ANTHROPIC_API_KEY`)이 적용됩니다.
+
+```an-diagram title="Fork PR consent gate" summary="Fork PRs get no secrets by default; trusted authors run automatically, and outside contributors require a fresh maintainer recap label."
+{
+  "html": "<div class=\"diagram-fork\"><div class=\"diagram-node\">Fork PR opened<br><small class=\"diagram-muted\">main workflow has no secrets</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">Trusted author</span><small class=\"diagram-muted\">OWNER, MEMBER, or COLLABORATOR runs automatically</small></div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">Outside contributor</span><small class=\"diagram-muted\">maintainer reviews diff, then applies <code>recap</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\">Gate checks<br><small class=\"diagram-muted\">fork PR? &amp; trusted or fresh label?</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">Recap runs<br><small class=\"diagram-muted\">base-repo code only · fork diff is text input</small></div></div>",
+  "css": ".diagram-fork{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.diagram-fork .diagram-arrow{font-size:20px;line-height:1}.diagram-fork .center{display:flex;flex-direction:column;align-items:center;gap:4px;text-align:center}.diagram-fork .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}"
+}
+```
+
+### 라벨 게이트 작동 방식
+
+1. 포크 기여자가 PR을 엽니다. GitHub는 포크 실행에서 비밀을 보류하기 때문에 일반적인 `pull_request` 워크플로는 건너뜁니다.
+2. 포크 워크플로는 PR 작성자 연결을 확인합니다. 신뢰할 수 있는 작성자(`OWNER`, `MEMBER` 또는 `COLLABORATOR`)는 열기, 동기화, 다시 열기 및 검토 준비 이벤트 시 자동으로 실행됩니다.
+3. 외부 기여자는 관리자에게 현재 차이점을 검토하도록 요구합니다(특히 프롬프트 주입 형태의 콘텐츠의 경우 - 아래 참조). 그런 다음 `recap` 라벨을 PR에 적용합니다.
+4. 외부 기여자 레이블 게이트는 헤드별로 SHA입니다. 기여자가 더 많은 커밋을 푸시하면 유지관리자가 새 차이점을 검토한 후 `recap`를 제거하고 다시 적용할 때까지 다음 동기화 이벤트를 건너뜁니다.
+
+### 포크 워크플로가 수행하는 작업과 NOT가 수행하는 작업
+
+| 워크플로우 DOES                                                                                                        | 워크플로는 NOT를 수행합니다                                             |
+| ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| **기본 브랜치 참조**에서 **기본 저장소**를 확인하세요 — 신뢰할 수 있는 코드만                                          | 포크에서 코드를 확인하거나 실행하세요                                   |
+| 포크 헤드를 원격 참조(`git fetch origin pull/<n>/head:refs/recap/fork-head`)로 가져옵니다. 커밋 가져오기는 안전합니다. | 포크에서 패키지 설치, 포크 스크립트 실행 또는 포크 콘텐츠를 코드로 평가 |
+| `git diff base...refs/recap/fork-head` 실행 — 이미 가져온 두 개체의 순수 텍스트 비교                                   | LLM에 대한 텍스트 입력 이외의 다른 것으로 diff를 사용하십시오.          |
+| **기본 저장소** 시각적 요약 기술 및 에이전트 구성 실행                                                                 | 포크에서 스킬이나 구성을 로드하세요                                     |
+| 자사 PR과 동일한 비밀 스캔 단계(장애 종료)를 통해 차이점을 전달                                                        | 비밀 스캔 건너뛰기                                                      |
+| 차이점 콘텐츠를 신뢰할 수 없음으로 표시하는 에이전트 프롬프트에 명시적인 프롬프트 강화 메모를 추가하세요.              | 에이전트에게 일반 요약 에이전트 이상의 추가 권한 부여                   |
+
+### 라벨을 지정하기 전에 차이점을 검토해야 하는 이유
+
+포크 diff는 요약 에이전트가 입력으로 읽는 공격자가 제어하는 텍스트입니다. 신중하게 제작된 diff에는 요약 에이전트가 의도하지 않은 actions를 가져오도록 하기 위한 프롬프트 삽입 콘텐츠(예: 에이전트 지침처럼 보이는 diff 줄)가 포함될 수 있습니다(예: 게시 토큰을 유출하거나 오해의 소지가 있는 요약 콘텐츠 생성).
+
+`recap` 라벨을 적용하기 전에 다음 사항에 대한 차이점을 훑어보세요.
+
+- 직접 명령이나 역할 지침처럼 읽는 줄("이전 지침 무시...", "현재는...", "토큰 쓰기...").
+- 시스템 프롬프트로 오해될 수 있는 비정상적인 파일 이름.
+- 지침으로 디코딩될 수 있는 추가된 파일의 인코딩된 콘텐츠.
+
+이러한 완화 기능은 이미 워크플로(비밀 스캔, 민감한 경로 게이트, 프롬프트 강화 메모, 제한된 에이전트 도구 허용 목록)에 계층화되어 있지만 라벨 검토가 기본 방어선입니다.
+
+### 기본 워크플로와의 관계
+
+두 개의 워크플로 파일은 독립적입니다. 비포크 PR 업데이트의 경우 `pr-visual-recap.yml`가 실행되는 유일한 워크플로입니다. 포크 PR의 경우 일반 워크플로는 포크 게이트에서 종료되고 `pr-visual-recap-fork.yml`는 신뢰할 수 있는 동일한 조직 작성자에 대해 자동으로 실행되거나 외부 기여자를 위한 새로운 유지 관리자 `recap` 레이블 이후에 자동으로 실행됩니다. 동일한 고정 댓글 표시와 계획 ID 스레딩을 공유하므로 PR과 포크 PR 모두 동일한 PR에 대해 단일 업데이트 댓글을 생성합니다.
+
+### 자체 수정 가드 {#self-modifying-guard}
+
+`gate` 단계는 PR이 다음 경로에 닿을 때 요약을 완전히 건너뛰므로 PR은 신뢰할 수 있는 요약 작업이 로드하고 비밀을 유출하는 워크플로, 기술 또는 에이전트 구성을 다시 작성할 수 없습니다.
+
+| 경로 패턴                                  | 이유                                     |
+| ------------------------------------------ | ---------------------------------------- |
+| `.github/workflows/pr-visual-recap.yml`    | 워크플로 자체                            |
+| `**/skills/visual-(recap\|plan\|plans)/**` | The visual-recap skill the agent follows |
+| `**/.claude/**`                            | 러너가 로드하는 에이전트 설정            |
+| `**/CLAUDE.md`                             | 러너가 로드하는 에이전트 지침            |
+| `**/AGENTS.md`                             | 러너가 로드하는 에이전트 지침            |
+| `**/.mcp.json`                             | 러너가 로드하는 MCP 서버 구성            |
+
+`BuilderIO/agent-native` 모노레포에서 워크플로는 PR 헤드 소스 대신 신뢰할 수 있는 기본 분기 소스에서 요약 CLI를 실행합니다. 이는 PR 수정 CLI 코드를 실행하지 않고도 요약에 적합하도록 `packages/core/**`를 포함한 일반적인 패키지 변경 사항을 유지합니다.
+
+## 로컬 파일 개인정보 보호 모드
+
+GitHub Action은 호스팅되고 공유 가능한 PR 검토를 위해 설계되었습니다. 원한다면
+요약 내용을 Agent-Native 계획 데이터베이스로 보내지 않고 요약하고
+로컬 파일 모드에서 로컬로 동일한 도우미 흐름:
+
+```bash
+npx @agent-native/core@latest recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
+npx @agent-native/core@latest recap scan --diff recap.diff
+npx @agent-native/core@latest recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
+```
+
+생성된 `recap-prompt.md`를 코딩 에이전트에 제공하세요. 로컬 파일 모드에서
+프롬프트는 에이전트에게 `plans/pr-123-visual-recap/plan.mdx`를 쓰라고 지시합니다
+선택적인 시각적 파일을 추가한 후 다음을 실행하세요:
+
+```bash
+npx @agent-native/core@latest plan local serve --dir plans/pr-123-visual-recap --kind recap --open
+```
+
+반환된 URL는 브라우저가 요약 MDX를 읽는 동안 호스팅된 계획 UI를 엽니다.
+로컬호스트 브리지에서. 요약 콘텐츠는 호스팅 계획에 기록되지 않습니다
+데이터베이스이며 URL는 브리지를 실행하는 시스템에서만 작동합니다. 달리면
+동일한 `PLAN_LOCAL_DIR`를 사용하여 로컬에서 Plan 앱
+`/local-plans/pr-123-visual-recap` 경로도 유효합니다. Repo 지원 폴더는
+`/local-plans/pr-123-visual-recap?path=plans%2Fpr-123-visual-recap`로 열립니다.
+이 모드는 호스팅된 고정 PR 댓글, 인라인 스크린샷 업로드를 비활성화합니다.
+명시적으로 게시할 때까지 사용법 첨부 파일 및 브라우저 설명
+
+## 게이트가 아닌 정보 제공
+
+요약은 일반적인 PR 흐름 위에 추가된 검토 보조 자료입니다.
+
+- 가시성을 위해 `Visual Recap` 검사 행을 표시하지만 **필수 검사는 아니며** 병합을 차단하지 않습니다.
+- 생성 또는 게시 실패는 중립적으로 완료되며 관련 없는 코드에 빨간색 X가 표시되는 것이 아니라 설명을 위한 끈적한 주석으로 표시됩니다.
+- 요약과 스크린샷은 **차이점이 검토되었음을 의미하지 않습니다**. 검토자는 실제 변경된 줄을 읽어야 합니다.
+
+## 버전 고정(복사 변형) {#version-pinning-copy-variant}
+
+기본적으로 복사 변형 워크플로는 런타임에 `@agent-native/core@latest`를 설치하므로 모든 요약 실행이 자동으로 최신 CLI를 선택합니다. CI에 재현 가능한 도구가 필요한 경우 **`RECAP_CLI_VERSION`** 저장소 변수를 설정하여 설치된 버전을 고정하세요.
+
+1. 저장소의 **설정 → 비밀 및 변수 → Actions → 변수**로 이동하세요.
+2. `1.5.0`와 같은 값을 사용하여 `RECAP_CLI_VERSION`라는 변수를 만듭니다.
+
+변수는 선택사항입니다. 최신 릴리스를 추적하려면 설정하지 않은 상태로 두거나 `latest`로 설정하세요.
+
+재사용 가능 호출자 변형의 경우 대신 `cli-version` 입력을 사용하세요(재사용 가능 섹션의 [Version pinning](#version-pinning) 참조).
+
+## 비밀 검사 허용 목록
+
+요약을 게시하기 전에 워크플로는 `npx @agent-native/core@latest recap scan`를 실행하여 차이점에서 가능성 있는 비밀을 감지합니다. diff가 알려진 비밀 패턴과 일치하는 PR은 설명 주석과 함께 차단됩니다. 요약은 게시되지 않으며 diff 콘텐츠는 코딩 에이전트로 전송되지 않습니다.
+
+드물게 저장소에 의도적인 테스트 픽스처 또는 표면적으로 비밀 패턴과 유사한 비밀이 아닌 문자열(예: 테스트 파일의 픽스처 키)이 있습니다. 거짓 긍정을 억제하려면 저장소 루트에 `.github/recap-scan-allowlist`를 생성하세요.
+
+### 형식
+
+공백이 아니고 주석이 아닌 각 줄은 **리터럴 하위 문자열** 또는 **`/regex/flags`** 패턴입니다.
+
+```
+# Lines starting with # are comments.
+
+# Literal substring — any diff line containing this string is allowed.
+sk-test-fixture1234567890abcdef
+
+# Regex pattern — written as /pattern/flags (JS syntax).
+/^.STRIPE_KEY=sk-test-/i
+
+# Another literal.
+EXAMPLE_API_KEY=placeholder-value
+```
+
+규칙:
+
+- 리터럴이 포함되어 있거나 전체 줄이 정규식과 일치하는 경우 해당 줄은 **억제**(허용)됩니다.
+- 파일은 **fail-closed**입니다. 파일이 없으면 억제가 적용되지 않습니다. 스캐너는 이전과 같이 작동합니다.
+- 빈 파일은 파일이 없는 것과 같습니다.
+- 잘못된 정규식 줄은 리터럴 문자열로 처리됩니다.
+
+허용 목록은 비밀 스캔 게이트에서만 참조됩니다. 코딩 에이전트가 읽을 수 있는 내용에는 영향을 미치지 않습니다. 게이트를 통과하면 에이전트는 관계없이 전체 차이를 받습니다.
+
+## 재사용 가능한 워크플로우로 채택
+
+### 재사용 가능한 변형을 사용하는 이유는 무엇입니까?
+
+기본 설치 프로그램은 전체 ~360줄 워크플로 YAML를 저장소에 복사합니다(**복사** 옵션). 이는 실행되는 모든 라인을 감사해야 하는 에어 갭 저장소 또는 저장소에 적합한 선택입니다. 단점은 버그 수정 및 개선 사항이 사용자에게 전달되지 않는다는 것입니다. 각 릴리스 후에 `npx @agent-native/core@latest recap setup`를 수동으로 다시 실행해야 합니다.
+
+**재사용 가능** 옵션은 대신 ~20줄의 얇은 호출자를 작성합니다. `uses:`를 통해 `BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml`에 위임합니다. 모든 호출자는 워크플로가 실행될 때 로컬 업데이트 없이 자동으로 최신 로직을 선택합니다.
+
+|                           | 복사(기본값)                             | 재사용 가능                     |
+| ------------------------- | ---------------------------------------- | ------------------------------- |
+| 저장소의 워크플로 크기    | ~360줄                                   | ~20줄                           |
+| 수정 사항을 자동으로 선택 | 아니요 — `recap setup`를 다시 실행하세요 | 예                              |
+| 에어갭/완전한 감사 가능성 | 예                                       | 아니요                          |
+| 특정 버전으로 고정 가능   | 로컬에서 편집하는 경우에만               | 예 — `uses:`에 `@v1.2.3`를 설정 |
+
+### 발신자 스니펫
+
+이것은 `npx @agent-native/core@latest recap setup --reusable`가 쓴 내용입니다(또는 수동으로 붙여넣을 수도 있습니다):
+
+```yaml
+name: PR Visual Recap
+
+# Thin caller — the full workflow logic lives in BuilderIO/agent-native.
+# Fixes and improvements reach this repo automatically on each run.
+# To pin a specific version for reproducibility replace '@main' with a
+# tag or SHA, e.g. '@v1.2.3' or '@abc1234'.
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review, closed]
+
+jobs:
+  visual-recap:
+    permissions:
+      actions: write
+      contents: read
+      checks: write
+      issues: write
+      pull-requests: write
+    uses: BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml@main
+    secrets:
+      PLAN_RECAP_TOKEN: ${{ secrets.PLAN_RECAP_TOKEN }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      PLAN_RECAP_APP_URL: ${{ secrets.PLAN_RECAP_APP_URL }}
+    with:
+      agent: ${{ vars.VISUAL_RECAP_AGENT || 'claude' }}
+      model: ${{ vars.VISUAL_RECAP_MODEL || '' }}
+      reasoning: ${{ vars.VISUAL_RECAP_REASONING || '' }}
+      skill-source: ${{ vars.VISUAL_RECAP_SKILL_SOURCE || 'auto' }}
+      # cli-version: "latest"  # pin to a specific @agent-native/core version
+```
+
+[Secrets and variables](#secrets-and-variables)에 설명된 것과 동일한 비밀 및 변수가 적용됩니다. 복사 변형과 동일한 방식으로 저장소 설정에서 설정하세요.
+
+### CLI를 통해 설치
+
+```bash
+# Write the thin caller instead of the full copy:
+npx @agent-native/core@latest recap setup --reusable
+
+# Or with a pinned ref for reproducibility:
+npx @agent-native/core@latest recap setup --reusable --ref v1.2.3
+```
+
+두 변형 모두 `.github/workflows/pr-visual-recap.yml`에 워크플로를 작성합니다. 기존 워크플로가 이미 있고 다른 경우 명령은 거부하고 `--force`를 전달하여 덮어쓰라고 지시합니다.
+
+작성 후 평소처럼 `npx @agent-native/core@latest recap doctor`를 실행하여 비밀이 구성되었는지 확인하세요.
+
+### 버전 고정
+
+기본적으로 호출자는 항상 재사용 가능한 워크플로의 최신 게시 버전을 사용하는 `@main`를 참조합니다. 재현 가능한 CI가 필요한 프로덕션 저장소의 경우 태그 또는 SHA에 고정하세요.
+
+```yaml
+uses: BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml@v1.2.3
+```
+
+`cli-version` 입력은 `@agent-native/core` CLI 버전이 워크플로 내에서 실행되는 것을 제어합니다. 최신 릴리스를 추적하려면 `"latest"`에 남겨두거나 완전한 재현성을 위해 버전 문자열(예: `"1.5.0"`)에 고정하세요.
+
+### workflow_call 이벤트 컨텍스트
+
+`workflow_call` 워크플로는 **발신자의** 이벤트 컨텍스트를 상속합니다. 재사용 가능한 워크플로는 `github.event.pull_request.*` 표현식을 사용하여 PR 번호, 헤드 SHA, 기본 SHA, 병합 타임스탬프 및 PR 메타데이터를 읽습니다. 이는 호출자가 `pull_request`에서 트리거하는 경우에만 올바르게 작동합니다. 위의 호출자 스니펫에는 이미 올바른 이벤트 유형이 포함되어 있습니다. `closed` 이벤트가 포함되어 병합된 PR 요약에 `merged_at` 스탬프를 찍고 나중에 배송된 작업으로 검색할 수 있습니다.
+
+`workflow_dispatch` 또는 `push`에서 호출자를 트리거하지 마세요. 해당 이벤트는 `pull_request` 페이로드를 전달하지 않으며 게이트는 "no pull_request 페이로드"로 요약을 건너뜁니다.
+
+## 관련
+
+- [Visual Plans](/docs/template-plan) — `/visual-plan` 및 `/visual-recap` skills, 호스팅된 계획 커넥터 및 이 작업이 게시되는 대화형 검토 표면.
+- [Skills](/docs/skills-guide) — 코딩 에이전트에 에이전트 네이티브 skills를 설치합니다.