@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ko-KR/faq.md

@@ -0,0 +1,142 @@
+---
+title: "FAQ"
+description: "에이전트 네이티브에 대한 일반적인 질문 - 그것이 무엇인지, 누구를 위한 것인지, 무엇을 빌드할 수 있는지, 어떻게 작동하는지."
+---
+
+# FAQ
+
+에이전트 네이티브에 대한 일반적인 질문은 '그냥 보고 있는 중입니다'부터 '지금 인증을 연결 중입니다.'까지 정리되어 있습니다.
+
+## 기본사항 {#general}
+
+### 에이전트 네이티브란 무엇인가요? {#what-is-agent-native}
+
+에이전트 네이티브는 AI 에이전트와 그 주변의 제품 표면이 동등한 파트너인 앱을 구축하기 위한 프레임워크입니다. 해당 표면은 하나의 사용자 지정 작업을 통해 헤드리스 에이전트로 시작하여 풍부한 채팅으로 성장하거나 완전한 UI가 될 수 있습니다. 변하지 않는 점은 에이전트와 인간이 동일한 actions, 데이터베이스 및 상태를 공유한다는 것입니다. 전체 설명은 [What Is Agent-Native?](/docs/what-is-agent-native)를 참조하세요.
+
+### 이것은 누구를 위한 것인가요? {#who-is-this-for}
+
+에이전트 네이티브는 실제 앱과 AI 에이전트가 동일한 데이터와 actions에서 작동하기를 원하는 사람들을 위한 것입니다. 일반적인 경로는 다음과 같습니다:
+
+- **설정 없이 메일, 캘린더, 양식, 계획 또는 기타 완성된 템플릿을 원하는 경우 호스팅된 앱을 사용하세요** — [template gallery](/templates)에서 시작하세요.
+- **채팅으로 시작** 사용자가 즉시 대화할 수 있는 기본 앱을 원한다면 actions 및 화면으로 확장하세요. [Getting Started](/docs/getting-started) 또는 [Chat](/docs/template-chat)로 시작하세요.
+- **UI에 커밋하기 전에 하나의 작업과 헤드리스 앱 에이전트 루프를 원하는 경우 기본 우선 시작** - [Getting Started](/docs/getting-started)로 시작하세요.
+- **인증, 데이터베이스, UI 및 에이전트 actions가 이미 연결되어 있는 자체 SaaS 제품을 원하는 경우 템플릿을 포크하고 사용자 정의**하세요. [Templates](/docs/cloneable-saas)를 참조하세요.
+- **처음부터 빌드** 새로운 에이전트 기반 제품을 위한 프레임워크 기본 요소를 원한다면 [Getting Started](/docs/getting-started)로 시작하세요.
+- **다른 에이전트 또는 코드 도구 연결** Claude, ChatGPT, Codex, Cursor 또는 GitHub Copilot/VS Code를 사용하여 에이전트 기본 앱을 사용하려면 — [External Agents](/docs/external-agents) 및 [Skills Guide](/docs/skills-guide)를 참조하세요.
+
+### 기존 앱에 AI를 추가하는 것과 어떻게 다릅니까? {#how-is-this-different}
+
+대부분의 앱은 앱에서 실제로 _할_ 수 없는 일을 나중에 고려하여 AI를 추가합니다. 에이전트 네이티브 앱에서 에이전트는 동일한 actions, 데이터베이스 및 상태를 UI와 공유하는 일급 시민이므로 버튼으로 할 수 있는 모든 작업을 수행하고 앱 자체 코드를 수정할 수 있습니다. [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder)를 참조하세요.
+
+```an-diagram title="Bolted-on AI vs. agent-native" summary="A bolted-on chat sidebar lives in its own world. An agent-native agent shares the same actions, database, and state as the UI."
+{
+  "html": "<div class=\"diagram-vs\"><div class=\"diagram-col\"><span class=\"diagram-pill warn\">Bolted-on AI</span><div class=\"diagram-node\">Chat sidebar</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>separate AI world<br><small class=\"diagram-muted\">can't touch the app</small></div><div class=\"diagram-box diagram-muted\">App UI &amp; data</div></div><div class=\"diagram-divider\" aria-hidden=\"true\"></div><div class=\"diagram-col\"><span class=\"diagram-pill ok\">Agent-native</span><div class=\"diagram-row2\"><div class=\"diagram-node\">UI</div><div class=\"diagram-node\">Agent</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>shared actions, DB &amp; state</div></div></div>",
+  "css": ".diagram-vs{display:flex;align-items:stretch;gap:18px;flex-wrap:wrap}.diagram-vs .diagram-col{display:flex;flex-direction:column;gap:8px;align-items:center;flex:1;min-width:200px}.diagram-vs .diagram-row2{display:flex;gap:8px}.diagram-vs .diagram-arrow{font-size:20px;line-height:1}.diagram-vs .diagram-divider{width:1px;align-self:stretch;background:currentColor;opacity:.15}"
+}
+```
+
+### 오픈소스인가요? {#is-this-open-source}
+
+그렇습니다. 프레임워크와 모든 템플릿은 오픈 소스입니다. 모든 것을 로컬에서 실행하거나 자체 호스트하거나 관리형 호스팅, 협업 및 팀 기능을 위해 Builder.io의 클라우드를 사용할 수 있습니다.
+
+### 비용은 얼마인가요? {#how-much}
+
+프레임워크 자체는 무료입니다. 실제로 보게 될 두 가지 비용은 다음과 같습니다.
+
+- **AI 사용.** 자신의 API 키(Anthropic, OpenAI 등)를 가져와 모델 제공자에게 직접 비용을 지불합니다. 우리는 마크업을 하지 않습니다.
+- **호스팅.** 호스트가 청구하는 금액은 얼마든지 가능합니다. 대부분의 템플릿은 소규모 워크로드의 경우 무료 계층(Netlify, Vercel, Cloudflare)에서 잘 실행됩니다.
+
+이 중 어느 것도 관리하고 싶지 않은 경우 `agent-native.com`(Builder.io에서 운영)의 호스팅 버전은 추론과 호스팅을 시트별 계획으로 번들로 제공합니다.
+
+### 내가 직접 호스팅할 수 있나요? {#can-i-self-host}
+
+그렇습니다. Node(Netlify, Vercel, Cloudflare, AWS, Deno Deploy, 자체 서버) 및 SQL 데이터베이스(Postgres, SQLite, Turso, D1)를 실행하는 호스트를 선택하세요. 프레임워크는 이식 가능하도록 구축되었습니다. [Deployment](/docs/deployment)를 참조하세요.
+
+### 어떤 AI 모델을 지원하나요? {#what-models}
+
+Anthropic Claude, OpenAI(GPT-5 제품군), Google Gemini 및 OpenAI API 형태를 사용하는 모든 제공업체(Ollama를 통한 현지 모델 포함). 설정에서 모델을 구성합니다. 전환은 코드 재작성이 아닌 구성 변경입니다. 프레임워크의 가장 무거운 테스트 경로는 Claude이므로 이것이 기본 권장 사항입니다.
+
+### AI/ML을 알아야 하나요? {#do-i-need-to-know-ai}
+
+아닙니다. 모델을 훈련하거나, 미세 조정하거나, 임베딩을 처리하지 않습니다. 일반 웹 앱을 빌드하고 호스팅 버전에서는 거의 아무것도 빌드하지 않습니다. 프레임워크는 메시지 라우팅, actions 실행, 상태 동기화 등 에이전트 통합을 처리합니다.
+
+### 기존 앱을 에이전트 기반 앱으로 마이그레이션할 수 있나요? {#can-i-use-existing-code}
+
+가능하지만 에이전트 네이티브는 처음부터 새로 구축했을 때 가장 잘 작동합니다. 공유 데이터베이스, 폴링 동기화, actions, 애플리케이션 상태 등 아키텍처가 전체적으로 통합되어야 합니다. 템플릿에서 시작하여 사용자 정의하는 것이 권장되는 경로입니다. 데스크톱 우선에서 모바일 우선으로 전환하는 것과 같다고 생각하세요. 개조할 수는 있지만 기본으로 구축하는 것이 더 좋습니다.
+
+## 템플릿 및 구축 가능한 항목 {#templates}
+
+### 어떤 템플릿을 사용할 수 있나요? {#what-templates-are-available}
+
+프레임워크에는 [Chat](/docs/template-chat), [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan)(시각적 계획 및 PR 요약), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch) 등을 포함한 프로덕션 준비 템플릿이 함께 제공됩니다. 각각은 UI, 에이전트 actions, 데이터베이스 스키마 및 AI 지침을 갖춘 완전한 앱입니다. 전체 카탈로그는 [Templates](/docs/cloneable-saas)를 참조하세요.
+
+### 템플릿을 맞춤설정할 수 있나요? {#can-i-customize-templates}
+
+그게 요점입니다. 템플릿을 포크하고 상담원에게 요청하여 맞춤설정하세요. "양식에 우선순위 필드를 추가합니다." "Salesforce 인스턴스에 연결하세요." "우리 브랜드에 맞게 색 구성표를 변경하세요." 에이전트가 코드를 수정하면 앱은 시간이 지남에 따라 발전합니다.
+
+### 템플릿에서 다루지 않는 것을 만들 수 있나요? {#build-from-scratch}
+
+그렇습니다. 기본 채팅 앱을 원한다면 `npx @agent-native/core@latest create my-chat-app --template chat`를 실행하세요. 내구성 있는 채팅 스레드, actions, 인증, SQL 지원 런타임 상태 및 자신만의 화면을 추가할 수 있는 공간이 제공됩니다. UI가 없는 가장 작은 작업 우선 앱을 원한다면 `npx @agent-native/core@latest create my-agent --headless`를 실행하세요. [Getting Started](/docs/getting-started), [Pure-Agent Apps](/docs/pure-agent-apps) 및 [Chat](/docs/template-chat)를 참조하세요.
+
+### 템플릿을 포크하지 않고 시도해 볼 수 있나요? {#try-with-a-skill}
+
+예 — 하나의 명령으로 이미 사용하고 있는 코딩 에이전트에 기술을 설치하면 스캐폴드가 필요하지 않습니다. 연습은 [Skills Guide](/docs/skills-guide#app-backed-skills)를 참조하세요.
+
+## 에이전트 기능 {#agent-capabilities}
+
+### 에이전트가 실제로 앱 자체 코드를 수정할 수 있나요? {#can-the-agent-modify-code}
+
+예, 기능입니다. 에이전트는 구성 요소, 경로, 스타일 및 actions를 안전하게 편집할 수 있습니다. "동질 집단 분석 차트 추가"를 요청하면 에이전트가 차트를 작성합니다. "Stripe 계정에 연결"을 요청하면 에이전트가 통합을 작성합니다. 모든 것이 일반적인 Git 추적 코드이므로 잘못된 변경 사항은 쉽게 되돌릴 수 있습니다.
+
+### 사용자가 앱 외부에서 상담원과 대화할 수 있나요? {#external-channels}
+
+그렇습니다. 동일한 에이전트가 웹 UI, Slack, Telegram, 이메일 및 기타 에이전트([A2A](/docs/a2a-protocol)를 통해)에서 실행됩니다. 동일한 메모리와 동일한 actions를 가진 동일한 에이전트이며 방금 다른 채널을 통해 도달했습니다. [Messaging the agent](/docs/messaging)를 참조하세요.
+
+### 상담원이 서로 대화할 수 있나요? {#can-agents-talk-to-each-other}
+
+예, [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol)를 통해 가능합니다. 모든 에이전트 기반 앱은 자동으로 A2A 엔드포인트를 얻습니다. 메일 앱에서 분석 에이전트에 태그를 지정하여 데이터를 쿼리할 수 있습니다. 에이전트는 사용 가능한 다른 에이전트를 찾아 프로토콜을 통해 호출하고 UI에 결과를 표시합니다. 구성이 필요하지 않습니다. 에이전트 카드는 템플릿의 actions에서 자동 생성됩니다.
+
+### 상담원은 앱에서 무엇을 볼 수 있나요? {#what-can-the-agent-see}
+
+에이전트는 사용자가 현재 무엇을 보고 있는지 항상 알고 있습니다. UI는 경로가 변경될 때마다 탐색 상태(어떤 보기가 열려 있는지, 어떤 항목이 선택되는지)를 데이터베이스에 기록합니다. 상담원은 조치를 취하기 전에 이 내용을 읽습니다. 이메일이 열려 있으면 상담원은 어떤 이메일인지 알 수 있습니다. 슬라이드가 선택되면 상담원은 어떤 슬라이드인지 알 수 있습니다. [Context Awareness](/docs/context-awareness)를 참조하세요.
+
+## 개발 질문 {#development}
+
+### 에이전트 네이티브에서는 어떤 AI 코딩 도구가 작동하나요? {#which-ai-tools-work}
+
+프로젝트 지침을 읽는 AI 코딩 도구입니다. 프레임워크는 AGENTS.md를 범용 표준으로 사용하고 특정 도구에 대한 심볼릭 링크를 자동 생성합니다.
+
+- **Claude 코드** — CLAUDE.md를 읽습니다(CLI 설정에 의해 AGENTS.md에서 심볼릭 링크됨)
+- **커서** — AGENTS.md를 직접 읽거나 프로젝트에 있는 경우 `.cursorrules`(커서의 기존 위치)를 읽습니다.
+- **Windsurf** — .windsurfrules를 읽습니다(CLI 설정에 의해 AGENTS.md에서 심볼릭 링크됨)
+- **Codex, Gemini 및 기타** — 내장된 에이전트 패널을 통해 작업
+- **Builder.io** — 시각적 편집 및 협업 기능을 갖춘 클라우드 호스팅 에이전트
+
+### 내 데이터베이스를 사용할 수 있나요? {#can-i-use-my-own-database}
+
+그렇습니다. `DATABASE_URL`를 설정하면 프레임워크가 이를 자동 감지합니다. 지원되는 데이터베이스에는 SQLite, Postgres(Neon, Supabase, plain), Turso(libSQL) 및 Cloudflare D1이 포함됩니다. 모든 SQL는 Drizzle ORM를 통해 방언에 구애받지 않습니다. 동일한 코드가 어디에서나 작동합니다.
+
+### 어디에 배포할 수 있나요? {#where-can-i-deploy}
+
+어디서나. 서버는 Nitro에서 실행되며 Node.js, Cloudflare Workers/Pages, Netlify, Vercel, Deno Deploy, AWS Lambda 및 Bun과 같은 배포 대상으로 컴파일됩니다. 관리형 배포를 위해 Builder.io의 호스팅을 사용할 수도 있습니다. [Deployment guide](/docs/deployment)를 참조하세요.
+
+## 건축 {#architecture}
+
+### WebSocket 대신 SSE에 폴링을 더한 이유는 무엇입니까? {#why-polling-not-websockets}
+
+SSE는 동일 프로세스 쓰기에 브라우저에 대한 즉각적인 경로를 제공하고, 경량 버전 카운터 폴링은 영구 소켓을 사용할 수 없는 서버리스 및 에지를 포함한 모든 배포 환경에서 작동하기 때문에 대체 수단으로 남아 있습니다. [Key Concepts — Live sync](/docs/key-concepts#polling-sync)를 참조하세요.
+
+```an-diagram title="SSE first, polling fallback" summary="Same-process writes stream instantly; a version-counter poll keeps serverless, edge, and cross-process writes convergent."
+{
+  "html": "<div class=\"diagram-transport\"><div class=\"diagram-box\" data-rough>DB write</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">SSE<br><small class=\"diagram-muted\">/_agent-native/events &middot; instant</small></div><div class=\"diagram-node\">Poll<br><small class=\"diagram-muted\">/_agent-native/poll &middot; universal fallback</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Browser refetch</div></div>",
+  "css": ".diagram-transport{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-transport .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-transport .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+### UI가 LLM를 직접 호출할 수 없는 이유는 무엇입니까? {#why-no-inline-llm-calls}
+
+AI는 비결정적이므로 피드백을 제공하고 일회성 버튼이 아닌 반복을 위한 대화 흐름이 필요하며 에이전트에는 인라인 호출에 부족한 코드베이스, 지침, skills 및 기록이 이미 있습니다. 에이전트를 통해 모든 것을 라우팅하면 Slack, Telegram 또는 다른 에이전트에서 앱을 구동할 수도 있습니다. [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge)를 참조하세요.
+
+### 이것이 라이브러리가 아닌 프레임워크인 이유는 무엇입니까? {#why-framework-not-library}
+
+공유 데이터베이스, 라이브 동기화, actions 시스템 및 애플리케이션 상태는 처음부터 함께 연결되어 있기 때문에 작동합니다. UI는 에이전트 변경 사항에 즉시 반응하고 에이전트와 통신하며 에이전트는 사용자가 보고 있는 내용을 이해합니다. 도서관은 당신에게 작품을 제공합니다. 이것은 아키텍처입니다. [Key Concepts](/docs/key-concepts)를 참조하세요.

package/docs/content/locales/ko-KR/file-uploads.md

@@ -0,0 +1,122 @@
+---
+title: "파일 업로드"
+description: "파일 업로드 저장소 구성 - 개발용 SQL 대체, 프로덕션용 Builder.io 또는 사용자 지정 공급자"
+---
+
+# 파일 업로드
+
+프레임워크는 구성 가능한 공급자를 통해 업로드를 라우팅하는 파일 업로드 추상화를 제공합니다. 템플릿은 `uploadFile()`를 호출하고 URL를 반환합니다. 스토리지 백엔드는 애플리케이션 코드를 변경하지 않고도 교체 가능합니다.
+
+## 작동 방식 {#how-it-works}
+
+업로드 요청은 활성 공급자에게 전달되는 `POST /_agent-native/file-upload`로 이동합니다. `GET /_agent-native/file-upload/status`에서 어떤 공급자가 구성되어 있는지 확인할 수 있습니다.
+
+공급자 해결 순서는 다음과 같습니다.
+
+1. **사용자 등록 공급자** — `registerFileUploadProvider()`를 통해 등록된 맞춤형 공급자
+2. **Builder.io 공급자** — 내장, Builder.io가 연결되면 자동으로 활성화됨
+3. **SQL 대체** — 파일을 데이터베이스에 base64로 저장합니다(프로덕션이 아닌 개발에 적합)
+
+```an-diagram title="Provider resolution order" summary="uploadFile() picks the first configured provider in order. The SQL fallback always exists so uploads work with zero setup."
+{
+  "html": "<div class=\"diagram-upload\"><div class=\"diagram-box\" data-rough>uploadFile()<br><small class=\"diagram-muted\">POST /_agent-native/file-upload</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-step\"><span class=\"diagram-pill accent\">1</span><div class=\"diagram-node\">User-registered<br><small class=\"diagram-muted\">registerFileUploadProvider() — S3, R2, GCS…</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill\">2</span><div class=\"diagram-node\">Builder.io<br><small class=\"diagram-muted\">auto when connected — CDN-served</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill warn\">3</span><div class=\"diagram-node\">SQL fallback<br><small class=\"diagram-muted\">base64 in DB — dev only</small></div></div></div></div>",
+  "css": ".diagram-upload{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-upload .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-upload .diagram-step{display:flex;align-items:center;gap:8px}.diagram-upload .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```an-api title="The upload endpoint" method="POST" path="/_agent-native/file-upload"
+{
+  "method": "POST",
+  "path": "/_agent-native/file-upload",
+  "summary": "Upload a file through the active provider and get back a public URL.",
+  "description": "Dispatches to the first configured provider in resolution order. Check the active provider at `GET /_agent-native/file-upload/status`.",
+  "request": { "contentType": "multipart/form-data" },
+  "responses": [
+    { "status": "200", "description": "{ url, id?, provider } — the public URL and which provider handled it." }
+  ]
+}
+```
+
+## 기본값: SQL 대체 {#sql-fallback}
+
+구성된 공급자가 없으면 파일은 리소스 시스템을 통해 SQL 데이터베이스에 base64 데이터로 저장됩니다. 이는 로컬 개발에서는 기본적으로 작동하지만 프로덕션에서는 권장되지 않습니다. 대용량 파일은 데이터베이스를 부풀리고 CDN가 없습니다.
+
+대체를 사용할 때 일회성 경고가 기록됩니다.
+
+## Builder.io 호스팅 {#builder-hosting}
+
+앱이 Builder.io에 연결되면 파일 업로드가 자동으로 Builder의 자산 호스팅으로 라우팅됩니다. 파일은 구성이 필요 없이 CDN에서 제공됩니다. 이는 권장되는 제작 설정입니다.
+
+## 맞춤 제공자 {#custom-providers}
+
+스토리지 백엔드(S3, Cloudflare R2, GCS 등)를 사용하려면 서버 플러그인에 사용자 지정 공급자를 등록하세요.
+
+```ts
+// server/plugins/file-upload.ts
+import { registerFileUploadProvider } from "@agent-native/core/file-upload";
+
+export default defineNitroPlugin(() => {
+  registerFileUploadProvider({
+    id: "s3",
+    name: "Amazon S3",
+    isConfigured: () => !!process.env.S3_BUCKET,
+    upload: async ({ data, filename, mimeType }) => {
+      const key = `uploads/${Date.now()}-${filename}`;
+      await s3Client.putObject({
+        Bucket: process.env.S3_BUCKET!,
+        Key: key,
+        Body: data,
+        ContentType: mimeType,
+      });
+      return {
+        url: `https://${process.env.S3_BUCKET}.s3.amazonaws.com/${key}`,
+        provider: "s3",
+      };
+    },
+  });
+});
+```
+
+## API 업로드 {#upload-api}
+
+`FileUploadProvider` 인터페이스:
+
+```ts
+interface FileUploadProvider {
+  id: string; // Unique id, e.g. "s3"
+  name: string; // Human-readable name
+  isConfigured: () => boolean; // True when ready (env vars set, etc.)
+  upload: (input: FileUploadInput) => Promise<FileUploadResult>;
+}
+
+interface FileUploadInput {
+  data: Uint8Array | Buffer; // File contents
+  filename?: string; // Original filename
+  mimeType?: string; // MIME type, e.g. "image/png"
+  ownerEmail?: string; // For per-user scoping in fallback
+}
+
+interface FileUploadResult {
+  url: string; // Public URL for the uploaded file
+  id?: string; // Provider-specific id
+  provider: string; // Which provider handled it
+}
+```
+
+actions 또는 서버 코드에서 `@agent-native/core/file-upload`의 `uploadFile()`를 사용합니다.
+
+```ts
+import { uploadFile } from "@agent-native/core/file-upload";
+
+const result = await uploadFile({
+  data: fileBuffer,
+  filename: "photo.jpg",
+  mimeType: "image/jpeg",
+});
+
+if (result) {
+  // Provider handled it — result.url is the public URL
+} else {
+  // No provider configured — handle SQL fallback yourself, or skip
+}
+```

package/docs/content/locales/ko-KR/frames.md

@@ -0,0 +1,153 @@
+---
+title: "프레임"
+description: "로컬 개발 프레임, 내장된 에이전트 패널, 클라우드 프레임 — AI 에이전트가 앱과 함께 실행되는 방식."
+---
+
+# 프레임
+
+모든 에이전트 기반 앱은 UI 앱 옆에 있는 AI 에이전트와 함께 실행됩니다. **프레임**은
+두 가지를 모두 호스팅하는 래퍼: 앱을 표시하고 에이전트에게 다음 작업을 수행할 수 있는 장소를 제공합니다.
+채팅, 실행 및 (개발자 내) 코드 편집. 세 개의 프레임이 하나의 런타임을 공유합니다:
+
+- **내장형 에이전트 패널** — `@agent-native/core`의 모든 앱에 포함됩니다.
+  이것은 개발 및 프로덕션 과정에서 앱이 자체적으로 렌더링하는 사이드바입니다.
+- **로컬 개발 프레임** — iframe에서 실행 중인 앱을 로드하는 얇은 래퍼
+  동일한 에이전트 패널과 그 옆에 통합 CLI 터미널을 추가합니다. 중고
+  이 저장소에 있는 템플릿의 로컬 개발을 위해
+- **Builder.io 클라우드 프레임** — 협업을 통해 관리되고 호스팅되는 프레임
+  시각적 편집 및 병렬 에이전트 실행
+
+앱 코드는 어떤 프레임을 호스팅하든 관계없이 동일합니다. 상담원이 말하는 것
+모든 경우에 동일한 actions 및 애플리케이션 상태를 통해 앱에 적용됩니다.
+
+```an-diagram title="Three frames, one runtime" summary="Your app and the agent panel are the same in every frame; only the wrapper around them changes."
+{
+  "html": "<div class=\"diagram-frames\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Embedded panel</span><small class=\"diagram-muted\">ships in every app · dev + prod</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Local dev frame</span><small class=\"diagram-muted\">app in an iframe + panel + CLI terminal</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Builder.io cloud frame</span><small class=\"diagram-muted\">hosted: collaboration · visual edit · parallel runs</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Same runtime<br><small class=\"diagram-muted\">your app · actions · application state</small></div></div>",
+  "css": ".diagram-frames{display:flex;flex-direction:column;gap:10px;align-items:stretch}.diagram-frames .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.diagram-frames .diagram-arrow{font-size:22px;line-height:1;align-self:center}"
+}
+```
+
+## 내장된 에이전트 패널 {#embedded-agent}
+
+삽입 패널은 앱이 렌더링하는 상담원 사이드바입니다. 함께 배송됩니다
+`@agent-native/core` —별도의 패키지 설치는 없으며 동일합니다
+개발 및 생산의 구성요소
+
+- `@agent-native/core/client`에서 `AgentPanel`로 내보냈으며
+  생산 전용 변형 `ProductionAgentPanel`.
+- 전체 Chat / CLI / Workspace 표면을 제공하므로 상담원 입력이 유지됩니다.
+  프레임워크의 다른 모든 곳에서 사용되는 공유 작성기 스택
+- 매 턴마다 `application_state.navigation`를 읽으므로 어느 것인지 이미 알고 있습니다.
+  현재 상태와 선택된 내용을 확인하세요. "이것"을 다시 설명할 필요가 없습니다.
+
+### 앱 및 코드 도구 모드 {#tool-modes}
+
+패널은 두 가지 도구 모드 중 하나로 실행됩니다.
+
+- **앱 모드** — 에이전트에는 앱 전용 도구만 있습니다: actions
+  `defineAction`로 정의되며 탐색 및 컨텍스트도 포함됩니다. 파일 시스템이 없거나
+  셸 액세스. 이것이 최종 사용자가 얻는 것입니다.
+- **코드 모드** — 공유 코딩 도구 추가(`bash`, `read`, `edit`, `write`)
+  앱 도구 위에 데이터베이스 액세스가 가능하므로 상담원이 앱의 설정을 변경할 수 있습니다
+  자신의 소스. 코드 요청이 통제됩니다: 메시지에 코드가 필요한 경우
+  (`type: "code"`) 코드 가능 프레임이 연결되어 있지 않으면 패널에
+  코드 변경에는 Agent Native 데스크톱 또는 Builder가 필요함을 설명하는 대화상자;
+  프레임이 연결되면 요청이 해당 프레임과 코드 에이전트로 라우팅됩니다
+  표시기는 작동하는 동안 표시됩니다(`useSendToAgentChat`). 정식의 경우
+  코딩 도구 목록 및 공유 UI 계약, 참조
+  [Agent-Native Code UI](/docs/code-agents-ui).
+
+```an-diagram title="Code-request gating" summary="A code-typed message needs a code-capable frame. With one connected, the request routes there; without one, the panel explains code changes need Desktop or Builder."
+{
+  "html": "<div class=\"diagram-gate\"><div class=\"diagram-node\" data-rough>message<br><small class=\"diagram-muted\">type: \\\"code\\\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>code-capable frame connected?</div><div class=\"diagram-col\"><div class=\"diagram-pill ok\">yes &rarr; route to frame, show code-agent indicator</div><div class=\"diagram-pill warn\">no &rarr; dialog: needs Desktop or Builder</div></div></div>",
+  "css": ".diagram-gate{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-gate .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-gate .diagram-arrow{font-size:22px;line-height:1}.diagram-gate .center{text-align:center}"
+}
+```
+
+"코드 모드"는 에이전트 기능 토글이며 환경 개발 모드와 다릅니다.
+(`NODE_ENV` / Vite). 클라이언트 후크는 `useCodeMode()`입니다. (참조
+역호환 별칭의 경우 [Compatibility notes](#compatibility).)
+
+로컬 개발 프레임에서 설정 톱니바퀴는 이러한 모드 사이를 전환합니다. 전환
+오프 코드 모드는 프레임의 자체 사이드바를 숨기고 앱의 인앱 에이전트를 표시합니다
+대신 iframe 내부의 사이드바를 사용하여 최종 사용자가 보는 내용을 정확하게 미리 볼 수 있습니다.
+
+## 통합 터미널 및 CLI 스위칭 {#cli-terminal}
+
+개발 중 패널에는 내장형 터미널이 포함되어 있습니다(`AgentTerminal`도
+`@agent-native/core/client`에서) PTY 서버가 지원합니다. 당신은 진짜를 실행할 수 있습니다
+앱 바로 옆에 CLI를 코딩하고 앱 간에 전환합니다. 터미널이 다시 시작됩니다
+선택한 CLI로
+
+지원되는 CLI는 핵심 CLI 레지스트리에서 나옵니다.
+(`packages/core/src/terminal/cli-registry.ts`). 이 명령만 허용됩니다
+생성 — PTY 서버는 레지스트리에 대해 요청된 명령의 유효성을 검사합니다
+삽입을 방지하기 위한 허용 목록:
+
+| CLI         | 명령       | 패키지 설치                 |
+| ----------- | ---------- | --------------------------- |
+| Claude 코드 | `claude`   | `@anthropic-ai/claude-code` |
+| Builder.io  | `builder`  | (내장)                      |
+| Codex       | `codex`    | `@openai/codex`             |
+| 제미니 CLI  | `gemini`   | `@google/gemini-cli`        |
+| 오픈코드    | `opencode` | `opencode-ai`               |
+
+선택한 CLI가 `PATH`에서 발견되지 않으면 터미널은 이를 다시 실행합니다.
+`npx --yes <install-package>@latest`(설치 패키지가 있는 경우)를 통해.
+기본 명령은 `claude`입니다. 언제든지 에이전트 패널 설정에서 CLI를 전환하세요.
+시간.
+
+## Builder.io 클라우드 프레임 {#cloud-frame}
+
+[Builder.io](https://www.builder.io)는 다음을 호스팅하는 관리되는 프레임을 제공합니다.
+클라우드에 있는 동일한 앱 및 동일한 에이전트 패널:
+
+- 실시간 공동작업 — 여러 사용자가 동시에 시청하고 상호작용할 수 있습니다.
+- 시각적 편집, 역할 및 권한.
+- 더 빠른 반복을 위한 병렬 에이전트 실행.
+- 모두가 하나의 호스팅 환경을 공유하는 팀 사용에 적합합니다.
+
+내장 패널의 코드 요청은 동일한 방식으로 Builder 프레임으로 라우팅됩니다.
+로컬 개발 프레임으로 라우팅되므로 위의 dev-vs-prod 동작은 다음과 같습니다.
+두 가지 모두에서 일관됩니다.
+
+## 런타임 API {#runtime-apis}
+
+이것들은 `@agent-native/core`와 함께 제공되며 앱이 사용자와 대화하는 데 사용됩니다.
+에이전트(호스팅하는 프레임에 관계없음):
+
+1. **메시지 보내기** — `sendToAgentChat()`가 에이전트에 메시지를 보냅니다.
+   `useSendToAgentChat()` 후크는 설명된 코드 요청 게이팅으로 이를 래핑합니다.
+   위에서 렌더링할 `codeRequiredDialog` 요소를 반환합니다. 참조
+   전체 사용법과 옵션을 위한 [Drop-in Agent](/docs/drop-in-agent).
+2. **생성 상태** — `useAgentChatGenerating()`는 에이전트가 언제 작동하는지 추적합니다.
+   실행 중이므로 UI는 에이전트를 직접 폴링하지 않고도 진행 상황을 표시할 수 있습니다.
+3. **폴링 동기화** — 데이터베이스 기반 동기화는 에이전트가 실행될 때 UI 캐시를 최신 상태로 유지합니다.
+   데이터 또는 애플리케이션 상태를 변경합니다.
+4. **액션 시스템** — `pnpm action <name>`는 동일한 호출 가능 항목으로 디스패치
+   actions 에이전트는 도구로 호출하므로 에이전트가 수행할 수 있는 모든 작업을 사용자도 수행할 수 있습니다.
+   스크립트.
+
+## 실행 {#running}
+
+내장된 에이전트 패널은 모든 앱의 일부입니다. 템플릿을 기반으로 하며
+이미:
+
+```bash
+npx @agent-native/core@latest create my-app --template mail --standalone
+cd my-app
+pnpm dev
+```
+
+로컬 개발 프레임(프레임워크 저장소의 비공개 `@agent-native/frame` 패키지)은 npm에 게시되지 않은 내부 도구 패키지입니다. iframe에 활성 앱의 개발 서버를 로드하고 그 옆에 내장된 패널을 마운트하여 `app` 쿼리 매개변수를 통해 앱을 선택합니다. 통합된 CLI 터미널에는 터미널에 필요한 로컬 코드와 PTY 액세스를 제공하는 Agent Native 데스크탑이 필요합니다. 그렇지 않으면 패널에 채팅 화면이 표시되고 CLI를 사용하려면 데스크톱을 열라는 메시지가 표시됩니다.
+
+## 호환성 참고 사항 {#compatibility}
+
+"코드 모드" 개념은 이전에 "개발자 모드"로 명명되었으므로 일부 하위 호환
+이름은 지속됩니다. 이전 통합을 유지하지 않는 한 이를 무시할 수 있습니다
+코드:
+
+- 기본 `AGENT_MODE` 환경 변수인 `/_agent-native/agent-chat/mode`
+  엔드포인트(페이로드 키가 여전히 `devMode`임) 및 `agent-chat.mode`
+  설정 키는 변경되지 않습니다.
+- `useDevMode()`는 `useCodeMode()`의 더 이상 사용되지 않는 별칭으로 남아 있습니다.

package/docs/content/locales/ko-KR/getting-started.md

@@ -0,0 +1,199 @@
+---
+title: "시작하기"
+description: "에이전트 앱을 만들고 skills 및 actions 지침을 이해한 다음 에이전트가 첫 번째 작업을 호출하는 것을 지켜보세요."
+---
+
+# 시작하기
+
+Agent-Native 앱은 AI 에이전트와 UI에 동일한 actions, 데이터 및
+상태. 기본 에이전트는 이를 안내하는 지침, 가르치는 skills를 통해 만들어집니다.
+반복 가능한 동작과 실제 작업을 수행할 수 있는 actions
+
+**완벽한 앱을 원하시나요?** 다양한 템플릿 중 하나를 복제하세요 —
+[Chat](/docs/template-chat), [Mail](/docs/template-mail),
+[Calendar](/docs/template-calendar), [Content](/docs/template-content),
+[Analytics](/docs/template-analytics) 및 [many more](/docs/cloneable-saas) —
+모든 기능을 갖춘 앱을 사용자 정의하세요.
+
+처음부터 새로 짓나요? 유일한 선택은 UI를 원하는지 여부입니다 —
+이후의 모든 것(명령 작성, skills 추가, actions 정의, 실행
+에이전트)는 어느 쪽이든 동일합니다.
+
+```an-file-tree title="A basic Agent-Native agent"
+{
+  "entries": [
+    { "path": "AGENTS.md", "note": "always-on instructions: purpose, rules, tone, and the map of what the agent can do" },
+    { "path": ".agents/skills/customer-research/SKILL.md", "note": "a reusable playbook the agent loads when the task matches" },
+    { "path": "actions/summarize-week.ts", "note": "typed code the agent, UI, CLI, HTTP, MCP, A2A, jobs, and webhooks can run" }
+  ]
+}
+```
+
+채팅 UI, 헤드리스 에이전트, 전체 앱으로 시작하든 마찬가지입니다.
+UI는 표면을 변경합니다. 지침, skills 및 actions는 에이전트에게
+지도 및 행동.
+
+## 1. 앱 만들기
+
+[Node.js 22+](https://nodejs.org) 및 [pnpm](https://pnpm.io)가 필요합니다.
+
+플래그 없이 `create`를 실행하면 시작할 방법을 묻습니다(전체 템플릿,
+채팅 또는 Headless)보다 먼저:
+
+```bash
+npx @agent-native/core@latest create my-app
+```
+
+또는 프롬프트를 건너뛰려면 플래그를 전달하세요.
+
+**UI를 원하시나요?** 채팅 템플릿에서 시작하세요. 현재 근무 중인 에이전트와
+맞춤형 채팅 UI, 추가하는 모든 작업이 자동으로 표시됩니다.
+
+```bash
+npx @agent-native/core@latest create my-app --template chat
+```
+
+**그냥 헤드리스 프리미티브인가요?** 헤드리스 시작 — 동일한 actions 및 에이전트
+루프, UI 쉘 없음:
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+```
+
+그런 다음 생성한 폴더에서 설치합니다.
+
+```bash
+cd my-agent # or my-app if you chose the Chat template
+pnpm install
+```
+
+이제부터 둘은 동일합니다.
+
+## 2. 작업 추가
+
+액션은 에이전트와 UI가 호출할 수 있는 작업 중 하나입니다. 양쪽 비계
+다음 예와 함께 제공:
+
+```an-annotated-code title="첫 번째 action"
+{
+  "filename": "actions/hello.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { z } from \"zod\";\n\nexport default defineAction({\n  description: \"로컬 에이전트에서 인사합니다.\",\n  schema: z.object({\n    name: z.string().default(\"world\"),\n  }),\n  http: { method: \"GET\" },\n  readOnly: true,\n  run: async ({ name }) => {\n    return { message: `Hello, ${name}!` };\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "도구 설명", "note": "에이전트는 `description`을 읽고 언제 도구로 호출할지 판단합니다." },
+    { "lines": "6-8", "label": "타입 계약", "note": "하나의 zod `schema`가 에이전트, UI, HTTP, MCP, A2A의 모든 입력을 검증합니다." },
+    { "lines": "9", "label": "HTTP verb", "note": "Opt this action into an auto-mounted HTTP endpoint." },
+    { "lines": "10", "label": "Read-only", "note": "`readOnly` marks the action as safe to call without approval and cacheable for queries." },
+    { "lines": "11-13", "label": "One implementation", "note": "The `run` body is the single source of truth that every surface executes." }
+  ]
+}
+```
+
+`hello`를 도메인의 첫 번째 실제 작업으로 바꾸세요. 한 번만 정의하면 됩니다.
+모든 표면이 이를 포착합니다.
+
+매 턴마다 적용해야 하는 안내를 위해 `AGENTS.md`를 사용하세요. 다음과 같은 경우 스킬을 사용하세요.
+에이전트에는 재사용 가능한 워크플로 또는 도메인 절차가 필요합니다. 다음과 같은 경우 작업을 사용하세요.
+에이전트는 데이터를 읽고, 쓰고, API를 호출하거나
+승인을 수행합니다.
+
+## 3. 실행해 보세요
+
+작업을 직접 호출:
+
+```bash
+pnpm action hello --name Steve
+```
+
+또는 상담원에게 전화해 달라고 요청하세요.
+
+```bash
+pnpm agent "Call the hello action for Steve and explain what happened."
+```
+
+채팅 템플릿에서 시작한 경우 앱을 실행하고 동일한 에이전트를 사용하세요.
+브라우저 — 정의한 모든 작업을 이미 호출할 수 있습니다.
+
+```bash
+pnpm dev
+```
+
+이제 해당 작업은 UI, CLI, HTTP, MCP, A2A,
+예약된 작업 및 webhooks. 한 번 정의하면 어디에서나 전화할 수 있습니다.
+
+```an-diagram title="One action, every surface" summary="A single defineAction file fans out to every consumer with no extra wiring."
+{
+  "html": "<div class=\"diagram-fan\"><div class=\"diagram-box\" data-rough>defineAction</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-surfaces\"><span class=\"diagram-pill\">Chat UI</span><span class=\"diagram-pill\">CLI</span><span class=\"diagram-pill\">HTTP</span><span class=\"diagram-pill\">MCP</span><span class=\"diagram-pill\">A2A</span><span class=\"diagram-pill\">Scheduled jobs</span><span class=\"diagram-pill\">Webhooks</span></div></div>",
+  "css": ".diagram-fan{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-fan .diagram-surfaces{display:flex;flex-wrap:wrap;gap:8px;max-width:420px}.diagram-fan .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 상태 내장
+
+헤드리스(headless)는 무국적(stateless)을 의미하지 않습니다. Actions, 세션, 애플리케이션 상태, 스레드,
+실행 기록 및 자격 증명은 모두 SQL에 있습니다. 지역적으로는
+`data/app.db`; 프로덕션에서는 `DATABASE_URL`를 설정합니다. 참조
+[Deployment](/docs/deployment).
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Headless is still a real app.** The app-agent loop persists sessions, threads, runs, settings, and credentials in SQL — it is not a stateless prompt. You can add a UI later without touching your actions or state."
+}
+```
+
+## UI 맞춤 설정
+
+채팅 템플릿에서 시작한 경우 UI를 편집할 수 있습니다. 채팅 자체
+`<AgentChatSurface>` 구성 요소를 기반으로 구축된 하나의 작은 경로입니다.
+
+```tsx
+// app/routes/_index.tsx
+import { AgentChatSurface } from "@agent-native/core/client";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-full" />;
+}
+```
+
+- **`app/routes/_index.tsx`** — 채팅 페이지. 제안 변경, 비어 있음
+  상태 및 레이아웃
+- **`app/root.tsx`** — 앱 셸.
+  에이전트.
+- `<AgentSidebar>`를 사용하여 에이전트를 어떤 화면에나 놓고 수동으로 작업할 수 있습니다.
+  `sendToAgentChat()`로 버튼을 누르거나
+  `useActionMutation()`.
+
+전체 구성 요소 세트는 [Drop-in Agent](/docs/drop-in-agent)를 참조하세요.
+작업 결과를 테이블로 렌더링하는 [Native Chat UI](/docs/native-chat-ui)
+일반 텍스트 대신 차트 및 입력된 카드
+
+**헤드리스로 시작했고 나중에 UI를 원하시나요?** 채팅 템플릿은 _is_ UI 온램프 —
+`app/` 레이어(React 라우터 + Vite)는 정확히 헤드리스 스캐폴드입니다.
+떠납니다. 가장 깔끔한 조치는 채팅에서 시작(또는 다시 스캐폴드)하는 것입니다.
+템플릿; `actions/`, 에이전트 및 SQL 상태는 변경되지 않고 그대로 유지됩니다. 참조
+그 사이의 모든 표면에 [Agent Surfaces](/docs/agent-surfaces)가 적용됩니다.
+
+## 프로젝트 구조
+
+```text
+my-app/
+  actions/         # Agent-callable actions
+  app/             # React frontend (UI templates only; omitted when headless)
+  server/          # Nitro API server (routes, plugins)
+  AGENTS.md        # Always-on agent instructions
+  .agents/         # Skills the agent can pull in when relevant
+  data/app.db      # Local SQLite state when DATABASE_URL is unset
+```
+
+## 다음 목적지
+
+- **[Key Concepts](/docs/key-concepts)** — 핵심 아키텍처: SQL, actions,
+  동기화 및 상황 인식
+- **[Actions](/docs/actions)** — 전체 작업 API: 스키마, HTTP, 인증 및
+  승인.
+- **[Agent Surfaces](/docs/agent-surfaces)** — 헤드리스, 채팅, 내장형 사이드카,
+  및 전체 앱
+- **[Drop-in Agent](/docs/drop-in-agent)** — React 앱에 상담원 채팅을 추가하세요.
+- **[Deployment](/docs/deployment)** — 앱을 자신의 도메인에 배치하세요.
+- **[FAQ](/docs/faq)** — 설정 및 제품 질문.