@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ko-KR/creating-templates.md

@@ -0,0 +1,411 @@
+---
+title: "템플릿 만들기"
+description: "자신만의 에이전트 기반 앱 템플릿을 만들고 게시하는 방법."
+---
+
+# 템플릿 만들기
+
+템플릿은 실제 워크플로를 해결하는 완전하고 포크 가능한 에이전트 기반 앱입니다. 자사 템플릿은 귀하가 사용하는 것과 동일한 프레임워크 표면으로 구축됩니다. UI용 React 경로, 데이터용 Drizzle SQL, 작업용 actions, 에이전트 동작용 작업 공간 리소스, 에이전트와 UI가 정렬 상태를 유지하도록 폴링 동기화합니다.
+
+좋은 템플릿:
+
+- 유용한 시드 데이터 또는 빈 상태 흐름을 사용하여 하나의 워크플로를 엔드 투 엔드로 해결합니다.
+- JSON 파일이 아닌 SQL에 지속성 상태를 저장합니다.
+- 앱 작업을 `defineAction()` actions로 정의합니다.
+- 애플리케이션 상태를 통해 탐색 및 선택을 노출합니다.
+- 명확하지 않은 작업 흐름을 위해 명확한 `AGENTS.md`와 집중된 skills를 제공합니다.
+- 필수 제공업체 및 비밀번호에 대한 온보딩 단계를 등록합니다.
+- 독립형 앱 및 다중 앱 작업 공간의 일부로 작동합니다.
+
+## 채팅에서 시작 {#start-from-chat}
+
+프레임워크 배선이 이미 갖춰진 최소한의 앱을 원할 경우 채팅 템플릿을 사용하세요.
+
+```bash
+npx @agent-native/core@latest create my-template --template chat --standalone
+```
+
+여러 앱이 있는 작업 영역의 경우 선택기를 실행하고 원하는 도메인 템플릿과 함께 Chat을 포함합니다.
+
+```bash
+npx @agent-native/core@latest create my-platform
+```
+
+Chat은 인증, 내구성 있는 채팅 스레드, SQL 지원 리소스, 도구, 애플리케이션 상태, actions 및 폴링 동기화를 제공합니다. 도메인 모델과 제품 UI를 추가합니다.
+
+아직 재사용 가능한 UI 템플릿을 구축하지 않은 경우 [Getting Started](/docs/getting-started#1-create-your-app)에서 헤드리스 온램프를 사용하세요. 하나의 작업을 정의하고 `pnpm agent`로 실행한 후 나중에 워크플로에 내구성 있는 표면이 필요할 때 UI를 추가하세요.
+
+## 프로젝트 구조 {#project-structure}
+
+모든 템플릿은 동일한 광범위한 레이아웃을 따릅니다.
+
+```an-file-tree title="Template project layout"
+{
+  "title": "my-template/",
+  "entries": [
+    { "path": "app/", "note": "React frontend" },
+    { "path": "app/root.tsx", "note": "HTML shell and providers" },
+    { "path": "app/routes/", "note": "React Router file routes" },
+    { "path": "app/components/", "note": "Template UI" },
+    { "path": "app/hooks/", "note": "UI state and data hooks" },
+    { "path": "actions/", "note": "defineAction operations — the single source of truth" },
+    { "path": "server/db/schema.ts", "note": "Drizzle schema" },
+    { "path": "server/plugins/db.ts", "note": "additive migrations" },
+    { "path": "server/plugins/", "note": "startup integrations" },
+    { "path": "server/routes/api/", "note": "custom routes only when actions are not enough" },
+    { "path": "shared/types.ts", "note": "shared client/server types" },
+    { "path": ".agents/skills/", "note": "<skill>/SKILL.md — agent guidance for complex workflows" },
+    { "path": "AGENTS.md", "note": "template-specific agent instructions" },
+    { "path": "package.json" },
+    { "path": "react-router.config.ts" },
+    { "path": "vite.config.ts" }
+  ]
+}
+```
+
+애플리케이션 상태에 대해 `data/` 디렉터리를 추가하지 마세요. 내구성 있는 앱 데이터는 SQL에 속하며 UI는 actions 또는 형식화된 서버 핸들러를 통해 이를 읽습니다.
+
+모든 템플릿의 네 가지 영역은 하나의 공유 작업 표면과 하나의 SQL 데이터베이스를 통해 함께 연결됩니다. 에이전트와 UI는 동일한 작업에 대해 동등한 파트너입니다.
+
+```an-diagram title="How a template's four areas connect" summary="The UI and the agent both reach SQL through the same actions; application state and polling sync keep them aligned."
+{
+  "html": "<div class=\"diagram-tmpl\"><div class=\"diagram-col\"><div class=\"diagram-node\">React UI<br><small class=\"diagram-muted\">app/routes · components</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">AGENTS.md · skills</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">defineAction()</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL via Drizzle<br><small class=\"diagram-muted\">additive schema</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">Polling sync</div></div>",
+  "css": ".diagram-tmpl{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-tmpl .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-tmpl .diagram-arrow{font-size:22px;line-height:1}.diagram-tmpl .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## SQL의 모델 데이터 {#data-models}
+
+SQLite, Postgres, D1, Turso, Supabase, Neon 및 기타 지원되는 백엔드에서 스키마 이식성을 유지할 수 있도록 프레임워크 Drizzle 도우미를 사용하여 도메인 테이블을 정의하세요.
+
+```ts
+// server/db/schema.ts
+import {
+  table,
+  text,
+  integer,
+  now,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const projects = table("projects", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  status: text("status", {
+    enum: ["draft", "active", "archived"],
+  })
+    .notNull()
+    .default("draft"),
+  sortOrder: integer("sort_order").notNull().default(0),
+  ...ownableColumns(),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+});
+
+export const projectShares = createSharesTable("project_shares");
+```
+
+스키마 변경은 추가되어야 합니다. `server/plugins/db.ts`에서 `runMigrations()`를 통해 테이블과 열을 추가합니다. 파괴적인 SQL, `drizzle-kit push`, 테이블 이름 바꾸기 또는 열 삭제를 사용하지 마십시오.
+
+앱 읽기 및 쓰기의 경우 Drizzle의 쿼리 빌더와 `drizzle-orm`의 이식 가능한 연산자를 사용하세요. Drizzle가 쿼리를 표현할 수 있는 경우 원시 SQL로 제품 코드를 작성하지 말고 템플릿의 `drizzle-orm/sqlite-core` 또는 `drizzle-orm/pg-core`에서 가져오지 마세요.
+
+```ts
+// server/plugins/db.ts
+import { runMigrations } from "@agent-native/core/db";
+
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'draft',
+      sort_order INTEGER NOT NULL DEFAULT 0,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      visibility TEXT NOT NULL DEFAULT 'private',
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    )`,
+    },
+  ],
+  { table: "my_app_migrations" },
+);
+```
+
+사용자 또는 조직 데이터를 보관하는 스키마를 추가하기 전에 [Database](/docs/database) 및 [Security](/docs/security) 문서를 사용하세요.
+
+## 작업을 Actions로 정의 {#actions}
+
+Actions는 앱 동작에 대한 단일 정보 소스입니다. 에이전트는 이를 도구로 호출하고 프런트엔드는 후크를 통해 호출하며 다른 앱은 MCP/A2A를 통해 연결할 수 있습니다.
+
+```an-annotated-code title="actions/create-project.ts"
+{
+  "filename": "actions/create-project.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { getDb } from \"../server/db/index.js\";\nimport { nanoid } from \"nanoid\";\nimport { z } from \"zod\";\nimport * as schema from \"../server/db/schema\";\n\nexport default defineAction({\n  description: \"Create a project.\",\n  schema: z.object({\n    title: z.string().min(1).describe(\"Project title\"),\n  }),\n  run: async ({ title }, ctx) => {\n    const db = getDb();\n    const id = nanoid();\n    await db.insert(schema.projects).values({\n      id,\n      title,\n      ownerEmail: ctx.userEmail,\n      orgId: ctx.orgId,\n    });\n    return { id, title };\n  },\n});",
+  "annotations": [
+    { "lines": "2", "note": "`getDb` is created per app via `createGetDb(schema)` in `server/db/index.ts`." },
+    { "lines": "8", "label": "Tool surface", "note": "The `description` is what the agent reads to decide when to call this action as a tool." },
+    { "lines": "9-11", "label": "타입 계약", "note": "One zod `schema` validates input from the agent, the UI, HTTP, MCP, and A2A." },
+    { "lines": "18-19", "label": "Scoped write", "note": "Stamp `ownerEmail` / `orgId` from `ctx` so the row is correctly scoped for sharing and access checks." }
+  ]
+}
+```
+
+읽기 전용 actions에는 `http: { method: "GET" }` 또는 `readOnly: true`를 사용하세요. 동일 회전 도구 호출과 동시에 실행하기에 안전한 actions를 변형하는 경우에만 `parallelSafe: true`를 사용하십시오. 샌드박스 도구에서 실행하면 안 되는 폭발 반경이 높은 actions에는 `toolCallable: false`를 사용하세요.
+
+## UI 구축 {#ui}
+
+경로는 `app/routes/`에 있으며 React 라우터 v7 파일 라우팅을 사용합니다. actions 또는 API 핸들러를 통해 데이터를 쿼리하고 기본적으로 돌연변이를 낙관적으로 만듭니다.
+
+```tsx
+import { useActionMutation, useActionQuery } from "@agent-native/core/client";
+
+export default function ProjectsPage() {
+  const { data: projects = [] } = useActionQuery("list-projects", {});
+  const create = useActionMutation("create-project");
+
+  return (
+    <button onClick={() => create.mutate({ title: "Launch plan" })}>
+      New project ({projects.length})
+    </button>
+  );
+}
+```
+
+에이전트, 다른 탭 또는 작업이 데이터를 변경할 때 React 쿼리가 새로 고침을 캐시하도록 앱 셸 근처에서 실시간 동기화를 한 번 연결합니다.
+
+```tsx
+import { useDbSync } from "@agent-native/core/client";
+import { useQueryClient } from "@tanstack/react-query";
+
+export function AppSync() {
+  const queryClient = useQueryClient();
+  useDbSync({ queryClient });
+  return null;
+}
+```
+
+**에이전트 네이티브 약속: 에이전트 쓰기는 수동 새로 고침 없이 UI에 표시됩니다.** `useActionQuery`는 쉬운 경로입니다. 변형 작업이 `source: "action"`를 내보낼 때 모든 후크가 다시 가져옵니다. 사용자 정의 키(예: 통합 상태를 읽는 하위 수준 클라이언트 도우미)를 사용하여 원시 `useQuery`에 도달하는 경우 대상 새로 고침을 위해 소스별 카운터를 queryKey에 접습니다.
+
+```tsx
+import { useChangeVersions } from "@agent-native/core/client";
+
+const v = useChangeVersions(["dashboards", "action"]);
+useQuery({
+  queryKey: ["dashboard", id, v],
+  queryFn: () => fetchDashboard(id),
+  placeholderData: (prev) => prev, // no flicker on refetch
+});
+```
+
+공통 소스: `"action"`(모든 성공적인 에이전트 작업 - 안정적인 대체), `"app-state"`, `"settings"` 및 스토어에서 `recordChange`를 통해 내보내는 모든 사용자 지정 리소스 소스. 전체 패턴은 `real-time-sync` 스킬을 참조하세요.
+
+## 애플리케이션 상태 추가 {#application-state}
+
+애플리케이션 상태는 에이전트가 사용자에게 표시되는 내용을 아는 방법입니다. 최소한 다음을 추가하세요:
+
+- 경로, 선택한 레코드, 활성 탭 또는 편집기 선택이 변경될 때 의미론적 `navigation` 상태를 작성하는 UI 후크.
+- 해당 상태를 읽고 현재 화면 스냅샷을 반환하는 `view-screen` 작업입니다.
+- UI가 사용할 원샷 `navigate` 명령을 작성하는 `navigate` 작업입니다.
+
+UI 후크에 `useAgentRouteState`를 사용하면 애플리케이션 상태 쓰기, 탭 범위 명령 읽기, 읽기 후 삭제 및 중복 명령 보호가 일관되게 유지됩니다.
+
+```tsx
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
+
+export function useNavigationState() {
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      selectedId: searchParams.get("id"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+    navigateOptions: { replace: true, flushSync: true },
+  });
+}
+```
+
+URL 쿼리 매개변수에 공유 가능한 필터를 유지합니다. 프레임워크는 이를 에이전트에 `<current-url>`로 노출하고 내장 에이전트는 이를 `set-search-params`로 변경할 수 있습니다. `navigation`는 전체 쿼리 문자열의 두 번째 복사본이 아닌 의미 체계 ID와 별칭을 보유해야 합니다.
+
+앱 탐색의 경우 동일한 출처를 포함하는 하나의 `navigate` 명령을 선호합니다
+URL가 알려진 경우 `path`. 동일한 동작에 `__set_url__`를 쓰지 마세요;
+해당 키는 프레임워크 URL 도구 및 URL 전용 필터 변경용으로 예약되어 있습니다.
+
+```ts
+// actions/navigate.ts
+import { defineAction } from "@agent-native/core/action";
+import { writeAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Navigate the UI.",
+  schema: z.object({
+    view: z.enum(["home", "project"]),
+    projectId: z.string().optional(),
+    path: z.string().optional(),
+  }),
+  run: async (args) => {
+    await writeAppState("navigate", args);
+    return { ok: true };
+  },
+});
+```
+
+전체 패턴은 [Context Awareness](/docs/context-awareness)를 참조하세요.
+
+## API 경로를 아껴서 사용 {#api-routes}
+
+앱 작동에는 actions를 선호합니다. 완전히 actions가 될 수 없는 표면에 대해서만 사용자 정의 Nitro 경로를 생성하세요:
+
+- 파일 업로드 또는 바이너리 스트리밍.
+- 공개 익명 페이지 및 webhooks.
+- OAuth 콜백 및 공급자별 프로토콜 핸들러.
+- 서버 렌더링 공개 콘텐츠
+
+소유 가능한 데이터를 다루는 사용자 정의 경로는 액세스 도우미를 사용하기 전에 `getSession(event)`를 호출하고 `runWithRequestContext({ userEmail, orgId }, fn)`에서 데이터베이스 작업을 래핑해야 합니다.
+
+## 쓰기 에이전트 지침 {#write-agents-md}
+
+`AGENTS.md`는 에이전트의 앱 맵입니다.
+목적 라인, 핵심 규칙, 애플리케이션 상태 키, 작업 테이블 및 skills
+색인:
+
+```markdown
+# My Template
+
+One workspace for projects, tasks, and notes.
+
+## Core Rules
+
+- Data lives in SQL via Drizzle. Use actions for all writes; schema is additive.
+- Use `view-screen` before acting on "this project" if the screen is unclear.
+
+## Application State
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## Actions
+
+| Action           | Purpose                  |
+| ---------------- | ------------------------ |
+| `list-projects`  | List accessible projects |
+| `create-project` | Create a project         |
+```
+
+새 작업, 경로, 상태 키 또는 반복 작업을 추가할 때마다 `AGENTS.md`를 업데이트하세요.
+워크플로. [Writing Agent Instructions](/docs/writing-agent-instructions)는
+전체 가이드 — `AGENTS.md`를 스키밍 가능하게 유지하는 방법, 네 가지 각각에 속하는 것
+안내 표면, 상담원이 기술 및 도구 설명을 단어로 표현하는 방법
+안정적으로 트리거합니다.
+
+## Skills 추가 {#skills}
+
+`AGENTS.md`를 부풀리는 세부 패턴(제공업체별 API, 가져오기/내보내기 형식, 복잡한 편집 흐름 또는 도메인 용어)에는 skills를 사용하세요.
+
+```markdown
+---
+name: project-imports
+description: How to import projects from the legacy CSV export.
+---
+
+# Project Imports
+
+Use this skill when the user uploads a legacy project CSV.
+
+## Rules
+
+- Validate required columns before creating rows.
+- Use `create-project` for each project so ownership and sync are correct.
+- Save rejected rows as a note attached to the import summary.
+```
+
+`.agents/skills/<name>/SKILL.md`에 템플릿 skills를 저장합니다. 사용자가 런타임에 지침을 편집할 수 있어야 하는 경우 작업공간 리소스를 통해서도 표시하세요.
+
+## 설정 단계 등록 {#onboarding}
+
+템플릿에 API 키, OAuth 연결 또는 공급자 계정이 필요한 경우 README에 요구 사항을 묻어두는 대신 온보딩 단계를 등록하세요.
+
+```ts
+// server/plugins/onboarding.ts
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { registerOnboardingStep } from "@agent-native/core/onboarding";
+
+export default defineNitroPlugin(() => {
+  registerOnboardingStep({
+    id: "github",
+    title: "Connect GitHub",
+    description: "Needed to import repositories and pull requests.",
+    order: 100,
+    methods: [
+      {
+        id: "token",
+        kind: "form",
+        primary: true,
+        label: "Save token",
+        payload: {
+          fields: [
+            { key: "GITHUB_TOKEN", label: "GitHub token", secret: true },
+          ],
+        },
+      },
+    ],
+    isComplete: () => !!process.env.GITHUB_TOKEN,
+  });
+});
+```
+
+[Onboarding & API Keys](/docs/onboarding)를 참조하세요.
+
+## 작업 공간에 적합하게 만들기 {#workspace-ready}
+
+Templates should fit naturally into [Multi-App Workspaces](/docs/multi-app-workspace), usually coordinated by [Dispatch](/docs/dispatch).
+
+체크리스트:
+
+- 프레임워크 에이전트 채팅 플러그인 또는 `mountA2A()`를 통해 A2A를 마운트하면 형제 앱이 에이전트를 호출할 수 있습니다.
+- Dispatch가 작업을 정확하게 전달할 수 있도록 상담원 카드 설명을 구체적으로 유지하세요.
+- 사이드바에 설정이 표시되고 Dispatch가 공유 자격 증명을 관리할 수 있도록 필수 비밀/온보딩을 등록하세요.
+- 작업 공간 `AGENTS.md` 또는 작업 공간 리소스에 교차 지침을 유지하고 모든 앱에 복사하지 마세요.
+- 소유 가능한 모든 리소스에 대해 공유/액세스 도우미를 사용하여 조직 범위의 작업 공간을 격리된 상태로 유지하세요.
+
+## 템플릿 게시 {#publishing}
+
+공유 전:
+
+1. `pnpm install`, `pnpm typecheck` 및 템플릿 테스트를 실행합니다.
+2. 선택적 공급자 키가 구성되지 않은 상태에서도 작동하는지 확인하세요.
+3. 인증, 공유, 두 사용자 데이터 격리를 확인하세요.
+4. 필요한 환경 변수 및 온보딩 단계를 문서화하세요.
+5. 추적된 런타임 데이터 파일이 아닌 추가 마이그레이션을 통해 예제 또는 시드 행을 포함합니다.
+
+GitHub 저장소에서 커뮤니티 템플릿을 생성할 수 있습니다:
+
+```bash
+npx @agent-native/core@latest create my-app --template github:user/repo
+```
+
+## 프레임워크 모노레포에 기여 {#contributing}
+
+### 게시되지 않은 프레임워크 변경 사항 테스트 {#test-unpublished-framework-changes}
+
+프레임워크 모노레포 내부에서 작업 중이고 생성된 파일이 필요한 경우
+게시되지 않은 패키지 또는 템플릿 변경 사항을 사용하려면 작업 공간을 사용하여 생성을 실행하세요.
+로컬 패키지 플래그:
+
+```bash
+AGENT_NATIVE_CREATE_USE_LOCAL_CORE=1 pnpm --filter @agent-native/core create my-platform
+```
+
+생성된 작업공간은 로컬 `@agent-native/core`와
+`@agent-native/dispatch` 패키지, 따라서 코어 API, 디스패치 작업 공간으로 변경됨
+게시하기 전에 동작이나 자사 템플릿을 테스트할 수 있습니다. 패키지
+`prepack` 스크립트는 연결하기 전에 `dist`를 빌드하여 생성된 내용을 유지합니다.
+현재 빌드 출력을 가리키는 작업공간.

package/corpus/core/docs/content/locales/ko-KR/cross-app-sso.md

@@ -0,0 +1,187 @@
+---
+title: "크로스앱 SSO"
+description: "Dispatch를 ID 기관으로 사용하여 ID 페더레이션을 통해 호스팅된 모든 에이전트 기반 앱에서 한 번 로그인합니다. 앱별로 옵트인하고 단일 환경 변수로 되돌릴 수 있습니다."
+---
+
+# 크로스앱 SSO
+
+`*.agent-native.com`에서 호스팅되는 각 앱은 **자체 별도의 사용자 스토어**를 통해 자체 배포를 실행합니다. `mail.agent-native.com` 및 `calendar.agent-native.com`는 데이터베이스, 세션 테이블 또는 쿠키 도메인을 공유하지 않습니다. 따라서 "한 번 로그인하면 모든 앱을 사용하세요"는 공유 쿠키가 될 수 없습니다. 이는 작업 공간에 대한 ID 권한 역할을 하는 [Dispatch](/docs/dispatch)를 사용하여 **ID 페더레이션**이어야 합니다.
+
+이것은 이미 사용하고 있는 동일한 신뢰 기본 요소 [A2A](/docs/a2a-protocol) 및 [External Agents](/docs/external-agents)(요청 경계에서 확인된 `A2A_SECRET` 서명 JWT)로 에이전트 간 호출 대신 인간 로그인 경로에 적용됩니다.
+
+> **통합 배포와 도메인별 배포.** 하나의 원본(`your-agents.com/mail`, `your-agents.com/calendar`)에서 모든 앱을 호스팅하는 경우 이미 단일 쿠키 도메인을 통해 공유 로그인을 받고 있으므로 페더레이션이 필요하지 않습니다. Cross-App SSO는 앱이 별도의 도메인에서 실행되는 경우에만 필요합니다. [Multi-App Workspaces — Unified deploy](/docs/multi-app-workspace#deployment)를 참조하세요.
+
+## 무엇과 이유 {#what-why}
+
+앱별 사용자 저장소는 모든 앱이 신뢰하는 브라우저 쿠키가 존재할 수 있는 단일 장소가 없다는 것을 의미합니다. 대신 페더레이션 모델은 하나의 앱(**Dispatch**)을 ID 기관으로 지정합니다. 다른 앱에서는 '이 사람이 누구인가요?'를 위임할 수 있습니다. Dispatch에 사용자의 확인된 이메일에 대한 단기 서명 어설션을 가져온 다음 **이메일을 통해 이를 자체 로컬 계정에 연결**합니다.
+
+연결 규칙은 의도적으로 범위를 좁히고 추가합니다.
+
+- **기존 동일 이메일 사용자 → 연결됨.** 로컬 계정은 확인된 이메일과 매칭되어 그대로 재사용됩니다. **수정되거나 이름이 바뀌거나 삭제되지 않습니다**. 페더레이션 레이어는 이를 읽고 세션을 생성하기만 합니다.
+- **새 이메일 → 생성됨.** 확인된 이메일에 대해 새로운 로컬 계정이 생성된 후 일반 로컬 세션이 생성됩니다.
+
+이렇게 하면 사람들이 로그아웃하더라도 출시가 안전해집니다. **로그아웃이 필요합니다.** 앱에서 이 기능을 켜면 기존 세션이 종료되고 Dispatch를 통해 사용자가 재인증을 받습니다. 하지만 항상 **모든 데이터가 그대로 유지된 상태로** 이메일과 일치하는 동일한 계정에 다시 로그인합니다. 왜냐하면 ID 행은 *추가*되기만 하고 파기되거나 이름이 변경되거나 다시 지정되지 않기 때문입니다.
+
+## 작동 방식 {#how-it-works}
+
+흐름은 표준 승인 → 서명된 토큰 → 콜백 리디렉션이며, 신뢰 경계를 넘는 유일한 것은 이메일입니다.
+
+```an-diagram title="Identity federation flow" summary="Dispatch authenticates the human and returns a short-lived signed assertion of one thing — the verified email. The app links by email and mints its own local session."
+{
+  "html": "<div class=\"diagram-sso\"><div class=\"diagram-card\" data-rough><strong>Client app</strong><small class=\"diagram-muted\">own user store</small></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill\">authorize</span></div><div class=\"diagram-card\" data-rough><strong>Dispatch</strong><small class=\"diagram-muted\">identity authority</small><span class=\"diagram-pill accent\">authenticates human</span></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill accent\">302 + signed JWT</span></div><div class=\"diagram-card\" data-rough><strong>App callback</strong><small class=\"diagram-muted\">verify signature · scope:identity · exp &le; 2 min</small><span class=\"diagram-pill ok\">JIT-link by email</span><span class=\"diagram-pill ok\">mint local session</span></div></div>",
+  "css": ".diagram-sso{display:flex;align-items:stretch;gap:12px;flex-wrap:wrap}.diagram-sso .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:150px}.diagram-sso .diagram-step{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:6px}.diagram-sso .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+1. **앱 → 디스패치(승인).** 앱이 사용자를 신원 인증 기관으로 보냅니다:
+
+   ```
+   GET https://dispatch.agent-native.com/_agent-native/identity/authorize
+       ?app=<requesting-app>
+       &redirect_uri=<app-callback-url>
+       &state=<csrf-state>
+   ```
+
+   ```an-api title="ID 인증 엔드포인트"
+   {
+     "방법": "GET",
+     "경로": "/_agent-native/identity/authorize",
+     "summary": "디스패치(ID 기관)는 사람을 인증하고 서명된 ID 토큰으로 다시 리디렉션합니다.",
+     "auth": "디스패치 세션(없는 경우 대화형 로그인)",
+     "매개변수": [
+       { "name": "app", "in": "query", "type": "string", "required": true, "description": "요청하는 앱 식별자입니다." },
+       { "name": "redirect_uri", "in": "query", "type": "string", "required": true, "description": "앱 콜백 URL. 엄격한 허용 목록(기본적으로 `*.agent-native.com` 또는 localhost)에 대해 검증되었습니다." },
+       { "name": "state", "in": "query", "type": "string", "required": true, "description": "CSRF 상태가 리디렉션 시 다시 에코되었습니다." }
+     ],
+     "응답": [
+       { "status": "302", "description": "단기 `A2A_SECRET` 서명 ID JWT(`scope: \"identity\"`, `exp` ≤ 2분)와 원본 `state`를 전달하는 `redirect_uri`로 리디렉션합니다." },
+       { "status": "400", "description": "`redirect_uri`가 허용 목록 유효성 검사에 실패했습니다(교차 출처, 스키마 기준 `//host` 또는 목록에 없는 접미사)." }
+     ]
+   }
+   ```
+
+2. **Dispatch는 사람을 인증합니다.** 사용자가 이미 Dispatch 세션을 가지고 있는 경우 이는 투명합니다. 그렇지 않은 경우 Dispatch는 자체 일반 로그인(이메일/비밀번호, Google 등 - [Authentication](/docs/authentication) 참조)을 표시합니다. Dispatch는 여기에서 일반적인 에이전트 기반 앱입니다. 특별한 인증 모드를 실행하고 있지 않습니다.
+
+3. **디스패치 → 앱(서명된 ID 토큰).** 디스패치는 엄격한 허용 목록에 대해 `redirect_uri`를 검증하고 단기 **`A2A_SECRET` 서명 ID JWT**를 전달하는 앱의 `redirect_uri`로 다시 302 리디렉션합니다. 토큰의 클레임은 의도적으로 최소화됩니다.
+
+   | 청구         | 의미                                              |
+   | ------------ | ------------------------------------------------- |
+   | `sub`        | 신원 기관의 안정적인 사용자 ID                    |
+   | `email`      | 사용자의 **확인된** 이메일 — 유일한 가입 키       |
+   | `name`       | 표시 이름(신뢰할 수 없음, UI에만 해당)            |
+   | `org_domain` | Workspace/org 도메인(있는 경우)                   |
+   | `scope`      | 항상 `"identity"` — 이 토큰은 로그인만 승인합니다 |
+   | `exp`        | **≤ 2분** 문제 발생 후                            |
+
+4. **앱은 이메일로 확인하고 JIT 연결합니다.** 앱은 자체 `A2A_SECRET`로 토큰 서명을 확인하고 `scope: "identity"` 및 `exp`를 확인한 다음 **확인된 이메일을 통해 엄격하게 적시 연결**을 수행합니다.
+   - 해당 이메일을 가진 로컬 사용자가 존재하는 경우 → 변경하지 않고 다시 사용하세요.
+   - 그렇지 않은 경우 → 해당 이메일에 대한 로컬 사용자를 생성하세요.
+
+5. **앱은 일반 로컬 세션을 생성합니다.** 여기에서 사용자는 해당 앱 자체 스토어에서 일반 로컬 세션을 갖게 됩니다. 기존의 모든 액세스 확인, 조직 범위 지정 및 작업 가드는 이전과 동일하게 작동합니다. 연맹은 정문에서만 이루어졌습니다.
+
+### 선택 {#opt-in}
+
+배포에 이 환경 변수가 설정된 경우 **만** 앱이 참여합니다.
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+- **설정** → 앱에 위의 흐름을 실행하는 **"Agent-Native로 로그인"** 옵션이 표시됩니다. 직접 로컬 로그인(이메일/비밀번호, Google)은 여전히 함께 작동합니다.
+- **설정 해제(기본값)** → **동작 변경 없음.** 앱은 이전과 동일하게 인증합니다. 페더레이션 코드 경로가 휴면 상태입니다. 스키마 변경이나 마이그레이션할 사항이 없으므로 변수를 켜거나 끄는 것은 언제든지 완전히 되돌릴 수 있습니다.
+
+## 보안 {#security}
+
+전체 모델은 의도적으로 몇 가지 작은 보장을 기반으로 합니다:
+
+- **단기 서명된 토큰.** ID 어설션은 **≤ 2분** 만료 및 `scope: "identity"`가 있는 `A2A_SECRET` 서명 JWT입니다. 단일 로그인을 승인하며 장기간 재생하거나 API/A2A 액세스를 위해 용도를 변경할 수 없습니다.
+- **엄격한 `redirect_uri` 허용 목록.** 디스패치는 기본적으로 `*.agent-native.com` 또는 localhost로만 리디렉션됩니다. 임의, 스키마 상대(`//host`) 및 교차 출처 리디렉션 대상은 거부되므로 해당 권한은 공개 리디렉션 또는 토큰 추출 오라클로 전환될 수 없습니다.
+- **확인된 토큰의 이메일 전용 가입.** 신뢰 경계를 넘는 _유일한_ 것은 서명된 토큰의 확인된 이메일입니다. 앱은 유선에서 사용자 ID, 역할, 조직 멤버십 또는 권한 있는 상태를 허용하지 않습니다. 일치하는 계정에서 로컬로 모든 것을 가져옵니다.
+- **추가 전용 ID 쓰기.** 연결하면 기존의 동일한 이메일 계정을 그대로 재사용하거나 새 계정을 삽입합니다. 이 경로에서는 ID 행의 업데이트, 이름 변경, 위치 변경 또는 삭제가 발생하지 않습니다.
+- **기본적으로 꺼져 있습니다.** `AGENT_NATIVE_IDENTITY_HUB_URL`를 설정하지 않으면 전체 기능이 비활성화됩니다.
+
+```an-callout
+{
+  "tone": "success",
+  "body": "**Safe to enable, safe to revert.** Identity writes are **additive only** — an existing same-email account is reused untouched, and a new email just inserts a fresh row. There is no schema change and nothing to migrate, so flipping `AGENT_NATIVE_IDENTITY_HUB_URL` on or off is fully reversible at any time, per app."
+}
+```
+
+적시 링크는 확인된 이메일에 전적으로 기반한 단일 결정입니다.
+
+```an-diagram title="JIT-link decision" summary="Linking is keyed on the verified email and is additive only — existing accounts are reused unchanged, new emails create a fresh local user."
+{
+  "html": "<div class=\"diagram-jit\"><div class=\"diagram-node\" data-rough>Verified email<br><small class=\"diagram-muted\">from signed identity JWT</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-branch\"><div class=\"diagram-box\" data-rough>Local user exists?<span class=\"diagram-pill ok\">yes &rarr; reuse unchanged</span><span class=\"diagram-pill accent\">no &rarr; create local user</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Mint normal local session</div></div></div>",
+  "css": ".diagram-jit{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-node{display:flex;flex-direction:column;gap:4px;padding:12px 14px}.diagram-jit .diagram-branch{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-box{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-jit .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 자체 호스팅 {#self-hosting}
+
+모든 Dispatch 배포는 ID 허브 역할을 할 수 있습니다. `dispatch.agent-native.com`로 제한되지 않습니다. Dispatch 인스턴스를 가리키도록 각 클라이언트 앱의 `AGENT_NATIVE_IDENTITY_HUB_URL`를 설정하세요.
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.yourcompany.com
+```
+
+**리디렉션 허용 목록.** 허브(Dispatch)는 토큰을 발행하기 전에 승인 엔드포인트에서 `redirect_uri`의 유효성을 검사합니다. 허용 목록은 `templates/dispatch/server/lib/identity-sso.ts`에서 구성됩니다:
+
+- **기본값:** `*.agent-native.com` 및 localhost 전용(`DEFAULT_ALLOWED_HOST_SUFFIXES` 상수).
+- **확장:** 쉼표로 구분된 추가 호스트 접미사 목록을 사용하여 Dispatch 배포에서 `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` 환경 변수를 설정합니다.
+
+  ````배쉬
+  # 기본값 외에 yourcompany.com 하위 도메인 허용
+  IDENTITY_SSO_ALLOWED_HOST_SUFFIXES=".yourcompany.com,.staging.yourcompany.com"
+  ```
+
+  각 항목은 점 접두사가 붙은 접미사(`.yourcompany.com`)로 정규화되므로 접미사 확인만으로 충분하고 문제가 가장 적습니다. 동기화할 앱별 목록이 없습니다. 모든 항목(비어 있거나 `.`만)과 일치하는 항목은 필터링됩니다.
+
+  ````
+
+- **로컬 호스트**는 `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`에 관계없이 클라이언트 측 앱의 로컬 개발에 항상 허용됩니다.
+
+`IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`가 없으면 자체 호스팅 디스패치는 `*.agent-native.com`의 앱에만 토큰을 발행할 수 있습니다. 다른 도메인을 잠금 해제하려면 Dispatch 배포에 환경 변수를 설정하세요.
+
+## 카나리아 출시 실행서 {#canary-rollout}
+
+컷오버 및 롤백은 **앱 배포당 단일 환경 변수**입니다. 한 번에 하나의 앱을 출시하고 확인한 후 확장하세요. 모든 앱에 변수를 한 번에 설정하지 마세요.
+
+**1. 코드 배포 — 동작 변경 없음**
+`AGENT_NATIVE_IDENTITY_HUB_URL` **모든 곳에서 설정되지 않음**을 사용하여 모든 앱에 릴리스를 제공합니다. 몇 가지 앱에서 일반 로그인이 여전히 작동하는지 확인하세요.
+
+**2. 한 번에 ONE 앱에서 카나리아를 활성화하세요.**
+설정, 하나의 배포에만 해당:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+다른 모든 앱의 환경은 설정되지 않은 상태로 둡니다. 변수를 선택하도록 재배포/다시 시작하세요.
+
+**3. 카나리아(체크리스트)를 확인하세요.**
+
+- 앱에서 로그아웃\*\*하세요.
+- 이제 로그인 화면에 **"Agent-Native로 로그인"**이 표시됩니다. 클릭하세요.
+- **Dispatch**로 이동하여 로그인을 완료합니다(또는 이미 로그인한 경우 바로 통과).
+- **다시 앱으로 리디렉션되어 로그인**됩니다. 이 계정은 새 계정이 아니라 이전에 사용했던 **동일한 기존 계정**(동일한 이메일)입니다.
+- **앱 데이터는 그대로 유지됩니다**. 기존 기록, 설정, 조직 범위 지정은 그대로 유지됩니다.
+- **기존 직접 로그인은 계속 작동합니다** — 이메일/비밀번호 및 Google 로그인은 SSO와 함께 계속 작동합니다.
+
+검사에 실패할 경우 바로 4단계(롤백)로 이동하세요. 즉각적이고 데이터가 안전합니다.
+
+**4. 앱별로 확장하세요.**
+하나의 앱이 확인되면 다음 앱에 대해 2~3단계를 반복합니다. 즉, 한 번에 하나의 배포에 `AGENT_NATIVE_IDENTITY_HUB_URL`를 설정합니다. 일괄 활성화하지 마세요.
+
+**5. 롤백 = 해당 앱 배포 시 환경 변수 설정을 해제합니다.**
+앱을 되돌리려면 **해당 앱 환경에서 `AGENT_NATIVE_IDENTITY_HUB_URL`를 제거하고 다시 배포/다시 시작하세요.** 앱은 즉시 이전 인증 동작으로 돌아갑니다. **실행 취소할 데이터 변경은 없습니다**. ID 행은 추가만 되었으며 변수를 설정 해제하면 페더레이션 경로가 다시 휴면 상태가 됩니다. 각 앱의 컷오버 및 롤백은 독립적이며 되돌릴 수 있습니다.
+
+> 롤아웃은 각 앱이 활성화될 때 사용자를 로그아웃하지만(Dispatch를 통해 다시 인증) 항상 **데이터가 그대로 유지된 동일한 이메일 일치 계정**에 다시 로그인합니다. 왜냐하면 ID 행은 절대 삭제되거나 이름이 바뀌지 않고 추가만 되기 때문입니다.
+
+## 관련 {#related}
+
+- [Authentication](/docs/authentication) — 로컬 인증 모드, 세션, 조직, `A2A_SECRET` 환경 변수
+- [A2A Protocol](/docs/a2a-protocol) — 서명된 JWT, 경계에서 검증 신뢰 모델을 재사용합니다.
+- [External Agents](/docs/external-agents) — 에이전트 연결 및 딥 링크에 적용되는 동일한 `A2A_SECRET` 서명 ID 패턴입니다.
+- [Dispatch](/docs/dispatch) — 작업 공간 ID 기관 및 라우팅 허브.
+- [Security & Data Scoping](/docs/security) — 추가 전용 데이터 쓰기 및 계정별 범위 지정.
+- [Multi-App Workspaces](/docs/multi-app-workspace) — 교차 도메인 SSO를 완전히 방지하는 통합 단일 원본 배포입니다.