@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ko-KR/blueprint-installer.md

@@ -0,0 +1,83 @@
+---
+title: "청사진 설치 프로그램"
+description: "agent-native add는 선별된 Markdown 통합 레시피를 stdout에 인쇄합니다. 이를 코딩 에이전트에 파이프하면 라이브 저장소에 대한 변경 사항이 적용됩니다."
+---
+
+# 청사진 설치 프로그램
+
+> **대상:** 공급자, 채널을 추가하는 호스트 작성자 및 통합자
+> 샌드박스 백엔드 또는 코딩 에이전트에 레시피를 연결하여 저장소에 대한 작업
+
+`agent-native add`는 파일을 작성해 주는 멍청한 스캐폴더가 **아닙니다**. 선별된 Markdown *통합 청사진*을 stdout으로 내보냅니다. 해당 청사진을 자체 코딩 에이전트(Claude 코드, Codex, …)에 파이프하면 전체 컨텍스트가 포함된 라이브 저장소에 대한 변경 사항이 적용됩니다.
+
+이것은 에이전트 적용 변경 사항, 파일 시스템 우선 하우스 스타일에 적합합니다. 프레임워크는 레시피(접촉할 표준 파일, 준수할 규칙, 확인 단계)를 제공하고 코딩 에이전트는 편집을 수행합니다.
+
+```bash
+agent-native add provider stripe | claude
+agent-native add channel discord  | codex
+```
+
+```an-diagram title="add prints a recipe; your coding agent applies it" summary="agent-native emits a Markdown blueprint to stdout (diagnostics to stderr); you pipe it into Claude Code or Codex, which edits your live repo with full context."
+{
+  "html": "<div class=\"diagram-bp\"><div class=\"diagram-node\" data-rough>agent-native add<br><small class=\"diagram-muted\">&lt;kind&gt; &lt;name|URL&gt;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Markdown blueprint<br><small class=\"diagram-muted\">stdout · files to touch · rules · Verify</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>Coding agent<br><small class=\"diagram-muted\">claude · codex</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">edits your live repo</div></div>",
+  "css": ".diagram-bp{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-bp .diagram-arrow{font-size:22px;line-height:1}.diagram-bp .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 용법 {#usage}
+
+```bash
+agent-native add <kind> <name>            # print a curated blueprint
+agent-native add <kind> <https://docs…>   # research-and-integrate from a URL
+agent-native add --list                   # list available kinds and blueprints
+```
+
+- 단순한 **이름**은 `blueprints/<kind>/<name>.md`에서 선별된 청사진을 해결합니다.
+- 이름 대신 **URL**는 URL가 연구 시작점으로 포함된 해당 종류에 대한 일반적인 _연구 및 통합_ 청사진을 내보냅니다(URL는 알려진 레시피가 아니라 연구 시드입니다).
+- 청사진은 **stdout**으로 이동합니다. 진단은 stderr로 이동하므로 `… | claude`는 청사진만 수신합니다.
+
+## 시드된 청사진 {#seeded}
+
+`agent-native add --list`는 상자에 무엇이 들어 있는지 보여줍니다:
+
+| 친절       | 이름      | 설정 내용                                                                          |
+| ---------- | --------- | ---------------------------------------------------------------------------------- |
+| `provider` | `stripe`  | 공급자를 `provider-api` 기판(카탈로그/문서/요청 트리오)에 연결합니다.              |
+| `channel`  | `discord` | `PlatformAdapter` 인바운드 웹훅 채널을 구현하고 등록하세요.                        |
+| `sandbox`  | `docker`  | Docker 컨테이너에서 `run-code`를 실행하려면 `SandboxAdapter` 솔기를 구현하세요.    |
+| `action`   | `crud`    | Zod 스키마가 있는 단일 다중 표면 `defineAction`를 추가합니다(N에 하나의 `update`). |
+
+각 청사진은 독립적입니다. 청사진을 읽는 코딩 에이전트는 파일을 가져오고, 프레임워크 규칙을 준수해야 합니다(actions는 단일 정보 소스이며, 비밀을 하드코딩하지 않으며, 소유할 수 있는 데이터 범위를 지정하고, `packages/*` 소스에 대한 변경 세트를 추가합니다). 구체적인 **확인** 섹션이 있습니다.
+
+## URL → 연구 청사진 {#url}
+
+URL를 전달하는 경우 해당 종류에 선별된 레시피가 없거나 새로운 통합을 원할 경우 `add`는 URL를 시드로 사용하여 일반적인 "연구 및 통합" 청사진을 내보냅니다.
+
+```bash
+agent-native add provider https://docs.example.com/api | claude
+```
+
+생성된 청사진은 코딩 에이전트에게 실제 엔드포인트, 인증 모델, 페이로드 형태 및 서명/검증 요구 사항에 대한 URL(및 링크된 페이지)를 가져온 다음(훈련 데이터에서 추측하지 _않음_) 구현하고 확인하도록 지시합니다. 또한 종류별 안내도 제공합니다(예: `provider` URL는 `provider-api` 기판 쪽으로 조종되고, `channel` URL는 `PlatformAdapter` 쪽으로 향합니다).
+
+## 나만의 청사진 추가 {#authoring}
+
+Markdown 파일을 `packages/core/blueprints/<kind>/<name>.md`에 놓습니다. 종류는 하위 디렉터리입니다. 이름은 `.md`가 없는 파일 이름입니다. 자동으로 선택됩니다. `--list`, 이름 확인 및 카탈로그는 모두 런타임 시 디렉터리를 읽습니다. 등록을 위해 코드 변경이 필요하지 않습니다.
+
+청사진 `.md` 파일은 `package.json` `files`의 `blueprints` 항목을 통해 게시된 패키지에 제공되므로 최종 사용자를 위해 `node_modules/@agent-native/core/blueprints/**`에서 확인됩니다.
+
+각 청사진을 다른 컨텍스트 없이 코딩 에이전트에 대한 명령 세트로 작성합니다. 좋은 청사진은 다음과 같습니다:
+
+1. **한 줄 목표** 및 "당신은 에이전트 네이티브 앱의 코딩 에이전트입니다. 이를 실제 소스 변경 사항으로 적용하십시오" 프레이밍
+2. **먼저 읽으십시오** — 계약서에 해당하는 정확한 파일을 읽어보세요.
+3. **만질 파일** — 구체적인 경로와 각 변경 사항이 수행하는 작업.
+4. **준수해야 할 프레임워크 규칙** — actions 우선, 하드코딩된 비밀 없음, 소유 가능한 데이터 범위, 게시 가능한 패키지 소스에 대한 변경 세트 추가.
+5. **검증** — 유형 검사, 집중된 `*.spec.ts` 및 엔드 투 엔드 검사.
+
+> [!TIP]
+> 기존 종류에 따라 새로 선별된 청사진에는 코드가 필요하지 않습니다. 하지만 새로운 종류 디렉토리를 생성하면 해당 종류가 `--list`에도 자동으로 표시됩니다.
+
+## 다음 단계
+
+- [**Sandbox Adapters**](/docs/sandbox-adapters) — `add sandbox docker` 청사진이 대상으로 하는 이음새
+- [**Actions**](/docs/actions) — 모든 청사진의 기반이 되는 단일 정보 소스
+- [**External Agents**](/docs/external-agents) — 청사진을 파이프하는 코딩 에이전트 연결

package/docs/content/locales/ko-KR/cli-adapters.md

@@ -0,0 +1,129 @@
+---
+title: "CLI 어댑터"
+description: "표준 어댑터 인터페이스(어댑터 가이드에서 다루는 두 개의 어댑터 연결부 중 하나)를 통해 에이전트에게 모든 CLI 도구(gh, ffmpeg, 스트라이프)에 대한 구조화된 액세스 권한을 부여하세요."
+---
+
+# CLI 어댑터
+
+> **적합한 경우:** CLI 어댑터는
+> 프레임워크. 정식 가이드는 [Adapters](/docs/sandbox-adapters)이며,
+> 이 솔기와 `run-code` 샌드박스 솔기를 모두 덮습니다 — 공유
+> 에지/서버리스 제약 조건. 이 페이지는 CLI 측에 대한 빠른 참조입니다.
+
+CLI 어댑터는 단일 명령줄 도구(`gh`, `ffmpeg`, `stripe`, `aws`)를 래핑하므로 에이전트는 이를 검색하고 설치 여부를 확인한 후 일관된 stdout/stderr/exit 코드 결과로 실행할 수 있습니다. 이 이음매가 없으면 모든 스크립트는 CLI를 호출하고 출력을 구문 분석하는 방법을 다시 고안합니다.
+
+```an-diagram title="CLI adapter → registry → action surface" summary="ShellCliAdapter wraps a binary; CliRegistry collects adapters for discovery; defineAction exposes one call on the agent + UI action surface."
+{
+  "html": "<div class=\"diagram-cli\"><div class=\"diagram-node\" data-rough>gh · ffmpeg · stripe<br><small class=\"diagram-muted\">command-line tools</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>ShellCliAdapter<br><small class=\"diagram-muted\">isAvailable · execute</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>CliRegistry<br><small class=\"diagram-muted\">describe() for discovery</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">defineAction</div></div>",
+  "css": ".diagram-cli{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-cli .diagram-arrow{font-size:22px;line-height:1}.diagram-cli .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 인터페이스 {#the-interface}
+
+모든 CLI 어댑터는 `CliAdapter`를 구현합니다:
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+## 쉘Cli어댑터 {#shell-adapter}
+
+대부분의 CLI에는 사용자 정의 클래스가 필요하지 않습니다. `ShellCliAdapter`는 합리적인 기본값으로 모든 바이너리를 래핑합니다.
+
+```ts
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const gh = new ShellCliAdapter({
+  command: "gh",
+  description: "GitHub CLI — manage repos, PRs, issues, and releases",
+});
+
+const ffmpeg = new ShellCliAdapter({
+  command: "ffmpeg",
+  description: "Audio/video processing and transcoding",
+  timeoutMs: 120_000, // 2 min for long encodes
+  env: { STRIPE_API_KEY: process.env.STRIPE_SECRET_KEY! },
+});
+```
+
+옵션: `command`(필수), `description`(필수), `name`(기본값은 `command`), `env`(`process.env`와 병합), `cwd`(기본값은 `process.cwd()`) 및 `timeoutMs`(기본값) `30000`).
+
+사용자 정의 인증, 출력 구문 분석 또는 사전/사후 처리의 경우 `ShellCliAdapter`를 사용하는 대신 `CliAdapter`를 직접 구현하세요.
+
+## 레지스트리 {#registry}
+
+`CliRegistry`는 에이전트가 런타임 시 사용 가능한 항목을 검색할 수 있도록 어댑터를 수집합니다.
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({ command: "gh", description: "GitHub CLI" }),
+);
+
+cliRegistry.list(); // all registered
+await cliRegistry.listAvailable(); // only installed
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+## actions에서 사용 {#from-actions}
+
+`defineAction`에서 CLI 호출을 래핑하여 작업 표면에 노출합니다. 코드가 서버 작업 표면 내부에서 실행될 때 `defineAction`가 필요합니다. 그렇지 않으면 `scripts/` 파일에서 직접 어댑터를 사용하십시오. 액션에서 `process.exit`를 호출하지 마세요. 대신 오류를 발생시킵니다.
+
+```ts
+// actions/list-prs.ts
+import { defineAction } from "@agent-native/core/action";
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+import { z } from "zod";
+
+const gh = new ShellCliAdapter({ command: "gh", description: "GitHub CLI" });
+
+export default defineAction({
+  description: "List open pull requests via the GitHub CLI.",
+  schema: z.object({}),
+  async run() {
+    if (!(await gh.isAvailable())) {
+      throw new Error("GitHub CLI not installed. Run: brew install gh");
+    }
+    const result = await gh.execute([
+      "pr",
+      "list",
+      "--json",
+      "title,url,state",
+      "--limit",
+      "10",
+    ]);
+    if (result.exitCode !== 0) {
+      throw new Error(result.stderr || "gh pr list failed");
+    }
+    return JSON.parse(result.stdout);
+  },
+});
+```
+
+## 에지 및 서버리스 {#edge-serverless}
+
+CLI 어댑터는 에지/작업자 런타임(Cloudflare Workers, Netlify Edge Functions)에 존재하지 않는 `node:child_process`를 사용합니다. 표준 Node.js 환경에서 CLI 어댑터 엔드포인트 및 작업을 실행하세요. 이 제약 조건은 샌드박스 이음새와 공유됩니다. [Adapters](/docs/sandbox-adapters#edge-serverless)의 전체 논의를 참조하세요.
+
+## 다음 단계
+
+- [**Adapters**](/docs/sandbox-adapters) — 두 어댑터 이음새에 대한 표준 가이드.
+- [**Actions**](/docs/actions) — 액션 표면 CLI 어댑터는 일반적으로 포장되어 있습니다.

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

@@ -0,0 +1,398 @@
+---
+title: "클라이언트"
+description: "에이전트 네이티브 앱용 React 후크 및 유틸리티: sendToAgentChat, 선택적 에이전트 채팅 컨텍스트 상태, useDbSync, useAgentChatGenerating 및 cn."
+---
+
+# 클라이언트
+
+`@agent-native/core`는 에이전트 네이티브 앱의 브라우저 측을 위한 React 후크 및 유틸리티를 제공합니다.
+
+이 클라이언트/React API는 `@agent-native/core` 및 `@agent-native/core/client` 모두에서 내보내집니다. 기본적으로 `@agent-native/core` 루트는 노드 빌드로 확인되므로 명확성과 올바른 번들링을 위해 `@agent-native/core/client`(브라우저 항목)에서 가져옵니다.
+
+파일 기반 라우팅(페이지, 동적 매개변수 및 탐색 추가)의 경우 [Routing](/docs/routing)를 참조하세요.
+
+## 데이터 가져오기 및 변형 {#fetching-mutating}
+
+브라우저에서 앱 데이터를 읽고 쓰는 기본 방법은 작업 후크를 이용하는 것입니다. `/_agent-native/*` 경로에 대한 `fetch` 호출을 직접 작성하지 마세요. 대신 명명된 도우미를 사용하세요([Actions](/docs/actions) 참조).
+
+```an-diagram title="The browser data loop" summary="Hooks read and write through actions; useDbSync watches the database so agent and background writes refetch the same caches automatically."
+{
+  "html": "<div class=\"diagram-client\"><div class=\"diagram-col\"><div class=\"diagram-node\">useActionQuery<br><small class=\"diagram-muted\">cached read</small></div><div class=\"diagram-node\">useActionMutation<br><small class=\"diagram-muted\">write + invalidate</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-box\" data-rough>Actions<br><small class=\"diagram-muted\">/_agent-native/actions/*</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-panel\" data-rough><strong>SQL database</strong></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">useDbSync &rarr; refetch on change</div></div>",
+  "css": ".diagram-client{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-client .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-client .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```tsx
+import {
+  useActionQuery,
+  useActionMutation,
+  callAction,
+} from "@agent-native/core/client";
+
+// Read: auto-cached, auto-invalidated on mutations
+const { data, isLoading } = useActionQuery("get-lead", { leadId });
+
+// Mutate: emits a change event so query caches refetch
+const { mutate, isPending } = useActionMutation("create-lead");
+mutate({ name: "Alice", company: "Acme" });
+
+// Imperative: for one-off calls outside a component
+await callAction("archive-lead", { leadId });
+```
+
+## sendToAgentChat(옵션) {#sendtoagentchat}
+
+UI 상호 작용에서 AI 작업을 위임하는 일반적인 방법인 postMessage를 통해 에이전트 채팅에 메시지를 보냅니다. 숨겨진 모델 컨텍스트의 경우 `context`를 전달하고 즉시 전송하려면 `submit: true`를 전달하거나 사용자가 먼저 검토하는 초안을 미리 채우려면 `submit: false`를 전달하세요.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client";
+
+// Auto-submit a prompt with hidden context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+`embedApp()`로 생성된 MCP 앱 삽입 내부, 자동 제출된 메시지
+(`submit` 생략 또는 `true`)은 MCP 앱 호스트 브리지로 전달됩니다.
+포함된 호스트에게 숨겨진 컨텍스트를 추가하고 표시되는 사용자 차례를 보내도록 요청합니다.
+`context`는 사용자 대면 채팅으로 게시되지 않고 모델 표시 상태를 유지합니다.
+`submit: false`는 MCP 앱이 로컬 미리 채우기/검토 동작을 유지하지 않기 때문에
+표준 초안 미리 채우기 API를 정의합니다. 내부적으로 제출된 채팅 경로입니다
+때때로 `agentNative.submitChat`로 나타납니다. 앱 코드는 호출해야 합니다
+그 이벤트를 직접 게시하는 것보다 `sendToAgentChat()`
+
+### 무음 배경 전송 {#background-send}
+
+UI 작업으로 실제 에이전트 작업을 시작해야 하는 경우 `background: true`를 사용하세요.
+사이드바 열기 또는 초점 맞추기. 그래도 일반 채팅 스레드/실행이 생성됩니다.
+에이전트의 도구/actions/context를 사용하고 다음을 통해 작업을 관찰 가능하게 유지합니다
+실행 트레이; 이는 원시적인 일회성 모델 호출이 아닙니다.
+
+```ts
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background`는 `newTab`와 쌍을 이루도록 고안되었으므로 숨겨진 작업은 수행되지 않습니다.
+사용자의 활성 대화를 덮어씁니다. UI인 경우 반환된 `tabId`를 사용하세요.
+후속 작업 상태를 연관시키거나 나중에 실행에 대한 딥 링크를 연결해야 합니다.
+
+### 에이전트채팅메시지 {#agentchatmessage}
+
+| 옵션                  | 유형        | 설명                                                                                 |
+| --------------------- | ----------- | ------------------------------------------------------------------------------------ |
+| `message`             | `string`    | 채팅에 전송된 시각적 메시지                                                          |
+| `context`             | `string?`   | 숨겨진 컨텍스트가 추가되었습니다(채팅 UI에는 표시되지 않음)                          |
+| `submit`              | `boolean?`  | true = 자동 제출, false = 미리 채우기만                                              |
+| `newTab`              | `boolean?`  | 이 메시지에 대해 별도의 채팅 스레드를 생성하세요                                     |
+| `background`          | `boolean?`  | `newTab`를 사용하면 탭에 초점을 맞추지 않고 실행하고 `RunsTray`에 실행을 표시합니다. |
+| `openSidebar`         | `boolean?`  | 사이드바를 열지 않고 제출/미리 채우려면 false로 설정                                 |
+| `projectSlug`         | `string?`   | 구조화된 컨텍스트를 위한 선택적 프로젝트 슬러그                                      |
+| `preset`              | `string?`   | 다운스트림 소비자를 위한 선택적 사전 설정 이름                                       |
+| `referenceImagePaths` | `string[]?` | 선택적 참조 이미지 경로                                                              |
+
+## 에이전트 채팅 컨텍스트 상태(고급) {#agent-chat-context-state}
+
+컨텍스트 상태 API는 양방향 동기화가 필요한 UI에 대한 선택적 배관입니다.
+단계적 컨텍스트 칩: 현재 단계적 항목을 작성기 외부에 렌더링
+항목이 이미 첨부되었는지 여부를 반영하거나 명시적으로 제공
+컨트롤 제거/삭제.
+
+간단한 "에이전트에게 보내기"를 위해 이러한 도우미에게 연락하지 마세요.
+"검토를 위해 이 초안을 미리 작성하세요" 흐름. `context`와 함께 `sendToAgentChat()` 사용
+그리고 `submit`도 있습니다.
+
+| API                               | 다음 경우에 사용                                                           |
+| --------------------------------- | -------------------------------------------------------------------------- |
+| `useAgentChatContext()`           | React 구성요소에는 라이브 스테이지 컨텍스트 목록이 필요합니다              |
+| `setAgentChatContextItem(item)`   | 명령형 코드는 하나의 키 컨텍스트 항목을 준비하거나 대체해야 합니다.        |
+| `listAgentChatContext()`          | React가 아닌 코드에는 단계적 컨텍스트의 일회성 스냅샷이 필요합니다.        |
+| `removeAgentChatContextItem(key)` | UI는 안정적인 `key`에 의해 하나의 단계적 컨텍스트 항목을 제거해야 합니다.  |
+| `clearAgentChatContext()`         | UI는 보기 또는 모드 재설정 후와 같이 모든 단계적 컨텍스트를 지워야 합니다. |
+| `refreshAgentChatContext()`       | 명령형 코드는 최신 지속 컨텍스트 스냅샷을 다시 읽어야 합니다.              |
+
+`useAgentChatContext()`는 `{ items, set, remove, clear, refresh }`를 반환합니다.
+
+## openAgentSettings(섹션?) {#openagentsettings}
+
+앱 설정 페이지나 설정 카드가 열려야 할 때 `openAgentSettings()`를 사용하세요
+에이전트 사이드바의 설정 탭. `"llm"`, `"secrets"`와 같은 섹션 ID를 전달하세요.
+`"automations"`, `"voice"` 또는 `"limits"`를 사용하여 특정 섹션을 엽니다.
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client";
+
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+`agent-panel:open-settings`를 직접 파견하는 것보다 이 도우미를 선호하세요.
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client";
+
+function SelectionContextButton({ record }: { record: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-record:${record.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Record",
+          context: JSON.stringify(record, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()`는 검사만 필요한 명령형 코드용입니다.
+현재 준비된 항목은 한 번입니다. `clearAgentChatContext()`는 의도적으로 광범위합니다. 사용
+하나의 선택만 변경된 경우 `removeAgentChatContextItem(key)`.
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| 옵션          | 유형       | 설명                                                           |
+| ------------- | ---------- | -------------------------------------------------------------- |
+| `key`         | `string`   | 기존 너겟을 대체하는 데 사용되는 안정적인 식별자               |
+| `title`       | `string`   | 작곡기 칩에 표시되는 짧은 라벨                                 |
+| `context`     | `string`   | 다음 제출 메시지에 숨겨진 컨텍스트가 포함됨                    |
+| `openSidebar` | `boolean?` | 기본값은 true입니다. false를 스테이지 컨텍스트에 자동으로 전달 |
+
+## askUserQuestion(opts) {#ask-user-question}
+
+사용자에게 앱 코드에서 객관식 질문을 하고 인라인으로 렌더링
+상담원 패널, **답변을 기다립니다**. 이는 클라이언트 측 쌍입니다.
+에이전트에 내장된 `ask-question` 도구: `GuidedQuestionPayload`를
+`"guided-questions"` 애플리케이션 상태 키(마운트된 위치
+`GuidedQuestionFlow`가 렌더링) 에이전트 패널을 표시하므로 질문은 다음과 같습니다.
+표시됩니다. 답변이 상담원에게 다시 전달되는 상담원 도구와는 달리
+`askUserQuestion()` **발신자의 응답으로 해결**하므로 UI는
+그쪽으로 가지를 치세요.
+
+UI가 실행하기 전에 정확히 하나의 작은 결정(2~4개 옵션)이 필요할 때 사용하세요.
+사용자 정의 모달을 구축하는 대신 에이전트 작업을 시작합니다.
+자유형 세부정보를 위한 작성기 및 다중 필드 입력을 위한 양식/팝오버
+
+```tsx
+import { askUserQuestion, sendToAgentChat } from "@agent-native/core/client";
+
+const length = await askUserQuestion({
+  question: "How long should this deck be?",
+  header: "Deck length", // optional short chip/heading (≈12 chars)
+  options: [
+    { label: "Short (3–5 slides)", value: "short" },
+    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
+    { label: "Long (11+ slides)", value: "long" },
+  ],
+  allowFreeText: false, // omit the "Other" free-text option (default adds it)
+  allowMultiple: false, // single-select (default)
+});
+
+if (length) {
+  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
+}
+```
+
+각 옵션은 `{ label, value?, description?, preview?, recommended? }`입니다. `value`
+기본값은 `label`이고 `preview`는 아래에 작은 모형/코드 조각을 렌더링합니다.
+option. The promise resolves with the selected `value` (or `value[]` when
+`allowMultiple`), 사용자가 "기타"를 선택한 경우의 자유 텍스트 문자열 또는 `null`
+건너뛰는 경우 — 사용자가 응답할 때까지 보류 상태로 유지됩니다. 에이전트 패널이 필요합니다
+마운트됩니다(모든 템플릿에 있음).
+
+에이전트는 `ask-question` 도구를 통해 동일한 UI에 도달합니다.
+에이전트는 *it*이 실제 포크에 도달하면 컨텍스트에서 해결할 수 없는지 묻습니다. 사용
+`askUserQuestion()` *UI*가 선택 항목에 대한 조치를 취해야 할 때
+
+## MCP 앱 호스트 브리지 {#mcp-app-host-bridge}
+
+MCP 앱으로 포함된 경로는 URL 우선이어야 합니다. 다음에서 현재 아티팩트를 로드합니다.
+경로/쿼리 매개변수, 실제 React 경로 또는 집중된 공유 구성요소 렌더링
+호스트 소유 동작에만 호스트 브리지를 사용합니다. `@agent-native/core/client`
+도우미가 포함된 경로 호출을 내보냅니다.
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client";
+```
+
+`getMcpAppHostContext()`는 최근 푸시된 호스트 컨텍스트 스냅샷을 읽습니다.
+`useMcpAppHostContext()`는 React 구성 요소를 변경 사항에 등록합니다. 요청
+도우미(`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
+`updateMcpAppModelContext`) 임베디드 MCP 앱 프레임 외부에서 `false`를 반환하거나
+프레임 내부의 `Promise<boolean>`. `sendToAgentChat()`는 동일한 브리지를 사용하여
+삽입된 경로에서 자동 제출된 프롬프트.
+
+브릿지 자체 — `ui/*` JSON-RPC 메시지, `agentNative.mcpHost.*`
+래퍼 릴레이, 이식 및 제어 프레임 렌더링, 호스트 컨텍스트
+디스플레이 모드 요청 — 소유
+[External Agents](/docs/external-agents#mcp-app-bridge).
+
+## 동적 제안 {#dynamic-suggestions}
+
+`<AgentSidebar>`, `<AgentPanel>` 및 `<AssistantChat>`는 기본적으로 정적 `suggestions`를 상황 인식 제안과 병합합니다. 프레임워크는 빈 채팅이 표시되는 동안 애플리케이션 상태에서 `navigation`, `selection`, `pending-selection-context` 및 현재 URL를 읽은 다음 현재 화면과 일치하는 프롬프트 칩을 제공합니다.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+정적 칩만 유지하도록 `dynamicSuggestions={false}`를 설정합니다. 앱이 동일한 애플리케이션 상태 컨텍스트에서 결정적인 도메인별 칩을 원하는 경우 `getSuggestions`를 전달하세요.
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+로드 상태 추적으로 sendToAgentChat을 래핑하는 React 후크:
+
+```ts
+import { useAgentChatGenerating } from "@agent-native/core/client";
+
+function GenerateButton() {
+  const [isGenerating, send] = useAgentChatGenerating();
+
+  return (
+    <button
+      disabled={isGenerating}
+      onClick={() => send({
+        message: "Generate a summary",
+        context: documentContent,
+        submit: true,
+      })}
+    >
+      {isGenerating ? "Generating..." : "Generate"}
+    </button>
+  );
+}
+```
+
+`isGenerating`는 `send()`를 호출하면 true로 바뀌고 에이전트가 생성을 마치면 자동으로 false로 재설정됩니다.
+
+## useDbSync(옵션?) {#usedbsync}
+
+SSE에 대한 데이터베이스 변경 사항을 수신하고 폴링으로 대체하며 UI를 에이전트 쓰기와 일치하도록 유지하는 프레임워크 쿼리 캐시를 무효화하는 React 후크(이전 `useFileWatcher`):
+
+```ts
+import { useDbSync } from "@agent-native/core/client";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+### 옵션 {#usedbsync-options}
+
+| 옵션               | 유형               | 설명                                                                                   |
+| ------------------ | ------------------ | -------------------------------------------------------------------------------------- |
+| `queryClient`      | `QueryClient?`     | 캐시 무효화를 위한 React 쿼리 클라이언트                                               |
+| `queryKeys`        | `string[]?`        | 더 이상 사용되지 않으며 무시됩니다. 기존 통화 사이트용으로 유지됨                      |
+| `pollUrl`          | `string?`          | 폴링 끝점 URL. 기본값: `"/_agent-native/poll"`                                         |
+| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only |
+| `interval`         | `number?`          | 폴링 간격(ms) 기본값: `2000`                                                           |
+| `fallbackInterval` | `number?`          | SSE를 사용할 수 없는 경우 대체 폴링 간격입니다. 기본값: `15000`                        |
+| `pauseWhenHidden`  | `boolean?`         | 브라우저 탭이 숨겨져 있으면 폴링을 일시 중지합니다. 기본값: `true`                     |
+| `ignoreSource`     | `string?`          | 탭이 자체 쓰기에서 다시 가져오지 않도록 무시할 탭별 요청 소스                          |
+| `onEvent`          | `(data) => void`   | SSE/폴링이 변경 이벤트를 수신할 때 선택적 콜백                                         |
+
+일반 CRUD의 경우 `useActionQuery` 및 `useActionMutation`를 선호합니다. actions를 변형하면 `source: "action"`가 방출되고 해당 후크는 자동으로 다시 가져옵니다.
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+프레임워크는 변경 버전을 사용하여 React 쿼리 캐시를 백그라운드 에이전트, 크론 작업 또는 다른 사용자가 변경한 내용과 동기화합니다.
+
+서버 측 데이터베이스 변형이 발생하면 서버는 특정 `source` 키를 사용하여 변경 이벤트를 기록합니다. 클라이언트의 `useDbSync` 수신기는 이러한 이벤트를 수신하고 해당 소스에 대한 로컬 변경 버전 카운터를 범프합니다. 버전 카운터를 React 쿼리 키에 추가하면 백엔드가 클라이언트에 새 활동을 알릴 때마다 쿼리가 자동으로 다시 가져옵니다.
+
+- **`useChangeVersion(source: string): number`** — 지정된 `source`가 변경될 때마다 증가하는 카운터를 반환합니다.
+- **`useChangeVersions(sources: readonly string[]): number`** — 여러 소스에 대한 버전 카운터의 합계를 반환합니다.
+
+### 예: 원시 쿼리를 데이터베이스와 동기화
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client";
+
+function DashboardView({ id }) {
+  // Get version for dashboards domain source
+  const v = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+### 지연 모델 및 무효화 동작
+
+- **UI 시작 돌연변이:** `useActionMutation`를 사용하여 UI에서 작업을 실행할 때 돌연변이는 성공 시 즉시 `source: "action"`를 사용하여 로컬 이벤트를 실행합니다. 이렇게 하면 해당 작업에 따라 모든 쿼리 키의 **즉각적이고 낙관적인 다시 가져오기**가 트리거되어 시각적 지연이 방지됩니다.
+- **백그라운드 또는 에이전트 돌연변이:** AI 에이전트, 웹훅 또는 백그라운드 작업자가 데이터를 변형하면 업데이트가 클라이언트에 브로드캐스트됩니다. 클라이언트의 `useDbSync`는 SSE(서버 전송 이벤트)를 통해 즉시 이를 캡처하거나 **2초 폴링 틱**으로 폴백합니다. 그런 다음 쿼리 키 버전이 충돌하여 백그라운드 다시 가져오기가 트리거됩니다.
+
+```an-diagram title="Two paths to a refetch" summary="A local mutation invalidates its own caches instantly; a remote write reaches this tab over SSE, or the polling tick as a fallback."
+{
+  "html": "<div class=\"diagram-latency\"><div class=\"diagram-col\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill ok\">This tab</span><strong>useActionMutation</strong><small class=\"diagram-muted\">fires source: \"action\" on success &rarr; instant local refetch</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Agent · webhook · other tab</span><strong>Remote write</strong><small class=\"diagram-muted\">SSE push, or the ~2s polling tick as fallback &rarr; version bumps &rarr; background refetch</small></div></div></div>",
+  "css": ".diagram-latency .diagram-col{display:flex;flex-direction:column;gap:12px}.diagram-latency .diagram-card{display:flex;flex-direction:column;gap:4px;padding:14px 16px}"
+}
+```
+
+## cn(...입력) {#cn}
+
+클래스 이름 병합을 위한 유틸리티(clsx + tailwind-merge):
+
+```ts
+import { cn } from "@agent-native/core/client";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```