@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ko-KR/workspace-connections.md

@@ -0,0 +1,321 @@
+---
+title: "작업공간 연결"
+description: "어디서나 연결 한 번 사용 통합을 위한 공유 공급자 메타데이터, 권한 부여 및 자격 증명 참조."
+---
+
+# 작업공간 연결
+
+작업 공간 연결은 재사용 가능한 통합 메타데이터를 위한 프레임워크 기본 요소입니다. 모든 공급자가 완전히 일반적인 것처럼 가장하지 않고도 "한 번 연결, 앱 부여, 자격 증명 재사용"이 가능해졌습니다.
+
+## 빠른 시작 {#quickstart}
+
+### 네 가지 개념
+
+- **연결** — 명명된 공급자 계정(`team-slack`, `acme-hubspot`). 공급자 ID, 계정 레이블, 상태, 범위 및 안전 구성을 기록합니다. 절대 비밀 값을 저장하지 마세요.
+- **허용** — 특정 앱이 연결을 사용할 수 있는 권한입니다. 권한이 부여되지 않은 앱은 연결 자격 증명을 볼 수 없습니다.
+- **credentialRef** — 저장소 비밀(`{ key: "SLACK_BOT_TOKEN", scope: "org" }`)에 대한 포인터입니다. 연결은 토큰이 어디에 있는지 알려줍니다. 금고에는 가치가 보관되어 있습니다.
+- **준비 상태** — 앱에 표시되는 결합 상태: `connected`(허용됨 + 자격 증명 존재), `needs_grant`, `needs_credentials`, `needs_attention` 또는 `not_configured`.
+
+```an-diagram title="Connect once, grant apps, reuse credentials" summary="A Connection holds provider metadata (never secrets) and credentialRefs that point at the vault. Per-app Grants unlock it. Apps read a single Readiness status."
+{
+  "html": "<div class=\"diagram-conn\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Connection</span><div class=\"diagram-box\" data-rough>named provider account<br><small class=\"diagram-muted\">provider, label, status, scopes, config &middot; never stores secret values</small></div><div class=\"diagram-muted\">credentialRef &rarr; pointer to a vault secret</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill\">Grant</span><div class=\"diagram-box\" data-rough>per-app permission<br><small class=\"diagram-muted\">no grant = no credential access</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Readiness</span><small class=\"diagram-muted\">what the app sees</small><div class=\"sev-row\"><span class=\"diagram-pill ok\">connected</span><span class=\"diagram-pill warn\">needs_grant</span></div><div class=\"sev-row\"><span class=\"diagram-pill warn\">needs_credentials</span><span class=\"diagram-pill warn\">needs_attention</span></div><div class=\"sev-row\"><span class=\"diagram-pill\">not_configured</span></div></div></div>",
+  "css": ".diagram-conn{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-conn .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-conn .diagram-arrow{font-size:22px;line-height:1}.diagram-conn .sev-row{display:flex;gap:8px;flex-wrap:wrap}"
+}
+```
+
+### 작업된 예: Slack
+
+Slack를 한 번 연결하고 Brain 및 Analytics에 부여하세요:
+
+```ts
+import {
+  upsertWorkspaceConnection,
+  upsertWorkspaceConnectionGrant,
+} from "@agent-native/core/workspace-connections";
+
+await upsertWorkspaceConnection({
+  id: "acme-slack",
+  provider: "slack",
+  label: "Acme Slack",
+  accountId: "T012345",
+  accountLabel: "Acme",
+  status: "connected",
+  scopes: ["channels:history", "groups:history", "chat:write"],
+  config: {
+    teamDomain: "acme",
+    channelHints: ["product", "dev-fusion", "customer-success"],
+  },
+  credentialRefs: [{ key: "SLACK_BOT_TOKEN", scope: "org" }],
+});
+
+await upsertWorkspaceConnectionGrant({
+  connectionId: "acme-slack",
+  appId: "brain",
+});
+await upsertWorkspaceConnectionGrant({
+  connectionId: "acme-slack",
+  appId: "analytics",
+});
+```
+
+```an-schema title="The connection model" summary="A connection records safe provider metadata and credentialRefs (pointers, not secrets). Each grant unlocks one app — one connection, many grants."
+{
+  "entities": [
+    {
+      "id": "conn",
+      "name": "workspace_connections",
+      "note": "Named provider account. Never stores secret values.",
+      "fields": [
+        { "name": "id", "type": "string", "pk": true, "note": "e.g. acme-slack" },
+        { "name": "provider", "type": "string", "note": "stable provider id, e.g. slack" },
+        { "name": "label", "type": "string" },
+        { "name": "accountId", "type": "string", "nullable": true },
+        { "name": "accountLabel", "type": "string", "nullable": true },
+        { "name": "status", "type": "string", "note": "e.g. connected" },
+        { "name": "scopes", "type": "string[]", "nullable": true },
+        { "name": "config", "type": "json", "nullable": true, "note": "safe, non-secret config" },
+        { "name": "credentialRefs", "type": "json", "nullable": true, "note": "pointers to vault keys, e.g. { key, scope }" }
+      ]
+    },
+    {
+      "id": "grant",
+      "name": "workspace_connection_grants",
+      "note": "Per-app permission to use a connection.",
+      "fields": [
+        { "name": "connectionId", "type": "string", "fk": "conn.id" },
+        { "name": "appId", "type": "string", "note": "e.g. brain, analytics" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "conn", "to": "grant", "kind": "1-n", "label": "grants apps" }
+  ]
+}
+```
+
+### 어떤 앱이 호출하는지
+
+사용자에게 새 키를 붙여넣도록 요청하기 전에 먼저 준비 상태를 확인하세요.
+
+```ts
+import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
+
+const catalog = await listWorkspaceConnectionProviderCatalogForApp({
+  appId: "brain",
+  templateUse: "brain",
+  provider: "slack",
+  includeConnections: "all",
+});
+
+const slack = catalog.providers[0];
+if (slack.workspaceConnection.grantState === "needs_grant") {
+  // Show "Grant Brain access" instead of asking for a second Slack token.
+}
+if (slack.readiness.status === "needs_credentials") {
+  // Show the missing credential ref names, never a secret value.
+}
+```
+
+## 참조 {#reference}
+
+### 제공자 카탈로그
+
+`@agent-native/core/connections`에서 카탈로그 가져오기:
+
+```ts
+import {
+  getWorkspaceConnectionProvider,
+  listWorkspaceConnectionProvidersForTemplate,
+  workspaceConnectionProviderSupports,
+} from "@agent-native/core/connections";
+
+const brainProviders = listWorkspaceConnectionProvidersForTemplate("brain");
+const slack = getWorkspaceConnectionProvider("slack");
+
+if (workspaceConnectionProviderSupports("slack", "messages")) {
+  // Offer a Slack source, sync check, or onboarding step.
+}
+```
+
+초기 공급자 ID는 다음과 같습니다:
+
+| 제공자         | 기능                       | 일반적인 용도                     |
+| -------------- | -------------------------- | --------------------------------- |
+| `slack`        | 검색, 가져오기, 메시지     | 브레인, 파견, 분석                |
+| `github`       | 검색, 가져오기, 코드, 문서 | 뇌, 분석, 파견                    |
+| `notion`       | 검색, 가져오기, 문서       | 뇌, 콘텐츠, 파견                  |
+| `gmail`        | 검색, 가져오기, 메시지     | 우편, 두뇌, 파견                  |
+| `google_drive` | 검색, 가져오기, 문서       | 브레인, 콘텐츠, 슬라이드          |
+| `hubspot`      | 검색, 가져오기, crm        | 분석, 브레인, 메일                |
+| `granola`      | 검색, 가져오기, 회의, 문서 | 뇌, 달력, 파견                    |
+| `clips`        | 검색, 가져오기, 회의       | 뇌, 클립, 비디오                  |
+| `generic`      | 검색, 가져오기, 문서       | 사용자 정의 webhooks 및 파일 삭제 |
+
+자격 증명 키는 `SLACK_BOT_TOKEN` 또는 `GITHUB_TOKEN`와 같이 이름일 뿐입니다. 공급자 메타데이터에는 실제 자격 증명 값이 포함되어서는 안 됩니다.
+
+### 연결 저장소 API
+
+```ts
+import {
+  listWorkspaceConnectionProviderCatalogForApp,
+  listWorkspaceConnectionGrants,
+  listWorkspaceConnections,
+  summarizeWorkspaceConnectionProviderForApp,
+  summarizeWorkspaceConnectionProviderReadiness,
+  upsertWorkspaceConnection,
+  upsertWorkspaceConnectionGrant,
+  revokeWorkspaceConnectionGrant,
+} from "@agent-native/core/workspace-connections";
+
+const connections = await listWorkspaceConnections({ includeDisabled: true });
+const grants = await listWorkspaceConnectionGrants({ appId: "brain" });
+
+const appGrant = summarizeWorkspaceConnectionProviderForApp({
+  providerId: "slack",
+  appId: "brain",
+  connections,
+  grants,
+});
+
+const readiness = summarizeWorkspaceConnectionProviderReadiness({
+  provider: slack!,
+  appId: "brain",
+  connections,
+  grants,
+});
+
+const brainCatalog = await listWorkspaceConnectionProviderCatalogForApp({
+  appId: "brain",
+  templateUse: "brain",
+});
+```
+
+`credentialRefs` 배열은 볼트 키를 가리킵니다. 자격 증명 저장소가 아닙니다. 예를 들어 `{ key: "SLACK_BOT_TOKEN", scope: "org" }`는 부여된 앱에 Slack를 호출해야 할 때 `SLACK_BOT_TOKEN`라는 조직 범위 Vault 비밀을 조회하도록 지시합니다. 연결 수준 참조는 공급자 계정을 설명합니다. 부여 수준 참조는 특정 앱이 사용해야 하는 항목을 좁히거나 재정의할 수 있습니다.
+
+연결 행은 활성 조직이 있는 경우 해당 조직으로 범위가 지정됩니다. 조직이 없으면 인증된 사용자로 범위가 지정됩니다. 부여 행은 동일한 범위를 사용합니다.
+
+**레거시 `allowedApps` 필드:** `allowedApps: []`는 동일한 범위에 있는 모든 앱이 연결을 사용할 수 있음을 의미합니다. `allowedApps: ["dispatch"]`는 레거시 필드를 통해 액세스 권한을 부여합니다. 새 설정에 명시적인 `workspace_connection_grants` 행을 사용하면 취소, 감사 및 앱별 준비가 더 쉬워집니다. `revokeWorkspaceConnectionGrant(connectionId, appId)`는 명시적 허가를 제거하지만 레거시 `allowedApps`를 변경하지 않습니다.
+
+수동 승인 확인 대신 앱 표시 상태에 `summarizeWorkspaceConnectionProviderForApp()` 및 `summarizeWorkspaceConnectionProviderReadiness()`를 사용하세요. 공유 요약은 `grantState`, `grantAvailability`, 안전한 자격 증명 참조 이름, 앱별 연결 행, `readyConnectionCount` 및 `missingRequiredCredentialKeys`와 같은 준비 필드를 반환합니다.
+
+새로운 앱 설정 화면의 경우 상위 수준 경계로 `listWorkspaceConnectionProviderCatalogForApp()`를 선호합니다. 이는 공급자 카탈로그, 범위 연결, 명시적 권한 부여, 앱별 액세스 요약 및 공급자 준비 상태를 하나의 안전한 형태로 결합합니다.
+
+### 이것이 금고를 보완하는 방법
+
+자격증명 저장소는 "비밀은 어디에 저장되어 있으며, 누가 액세스할 수 있으며 어떤 앱에 비밀이 부여됩니까?"라고 대답합니다.
+
+작업 공간 연결 공급자 메타데이터 답변: "이 공급자는 누구이며, 무엇을 할 수 있고, 어떤 자격 증명 키가 필요할 수 있으며, 어떤 템플릿을 제공해야 합니까?"
+
+```an-diagram title="Connection store vs. vault" summary="The vault owns the secret value. The connection owns provider metadata plus credentialRefs (pointers). At execution time the app resolves the ref through a granted connection and reads the value from the vault."
+{
+  "html": "<div class=\"diagram-vault\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Connection store</span><div class=\"diagram-box\" data-rough>provider account + metadata<br><small class=\"diagram-muted\">status, scopes, config</small></div><div class=\"diagram-box\" data-rough>credentialRef<br><small class=\"diagram-muted\">{ key: SLACK_BOT_TOKEN, scope: org }</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">App action</span><small class=\"diagram-muted\">resolves at execution time through a granted ref</small><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Vault</span><div class=\"diagram-box\" data-rough>secret value<br><small class=\"diagram-muted\">never returned to the agent or UI</small></div></div></div>",
+  "css": ".diagram-vault{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-vault .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-vault .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-vault .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+둘 다 함께 사용:
+
+1. 디스패치(또는 다른 작업공간 설정 흐름)는 기본 저장소 비밀 또는 OAuth 자격 증명 참조를 생성합니다.
+2. 작업공간 연결 저장소는 공급자 계정, 안전한 메타데이터, 자격 증명 참조 및 앱 부여를 기록합니다.
+3. 각 앱은 카탈로그에서 공급자 메타데이터를 읽고 공유 저장소에서 연결/부여 요약을 읽습니다.
+4. UI 앱은 연결됨, 부여되었지만 비정상, 부여 필요, 자격 증명 누락 또는 메타데이터 전용 등의 준비 상태를 보여줍니다.
+5. 앱별 SQL는 앱별 소스 ID, 커서, 필터, 동기화 창, 측정항목 정의, 검토 규칙 및 사용자 선택만 저장합니다.
+6. 앱 actions는 부여된 연결 참조 및 저장소를 통해 실행 시 자격 증명을 확인하고 비밀 값을 반환하지 않습니다.
+
+### 제공자 리더 런타임
+
+제공자-리더 계층은 모든 제공자가 공유된 라이브 리더를 갖는다는 약속이 아니라 먼저 계약입니다. 리더 정의는 지원되는 작업, 자격 증명 요구 사항 및 구현 상태(`metadata-only`, `template-owned` 또는 `shared`)를 설명합니다. 런타임은 앱에 대해 부여된 작업공간 연결 및 자격 증명 참조를 확인하고, 등록된 핸들러를 호출하고, 비밀 값을 노출하지 않고 정규화된 항목을 반환합니다.
+
+현재 대부분의 라이브 핸들러는 템플릿을 소유하고 있습니다. 즉, Brain은 여전히 Slack/GitHub 수집 동작을 소유하고 Analytics는 여전히 분석 해석을 소유하고 있습니다. 공급자별 API 호출, 페이지 매김, 권한 및 결과 의미 체계가 템플릿 전체에서 실제로 재사용 가능한 경우에만 리더를 `shared`로 승격하세요.
+
+### 앱 준비 패턴
+
+공유 공급자 자격 증명을 사용하는 앱은 읽기 전용 준비 작업과 다음을 포함하는 작은 설정 표면을 노출해야 합니다.
+
+- **공급자 카탈로그:** `@agent-native/core/connections`의 공급자 ID, 레이블, 기능, 권장 템플릿 사용 및 필수 자격 증명 키 이름.
+- **작업 공간 요약:** `@agent-native/core/workspace-connections`의 연결 수, 활성/허가된 수, 부여 상태, 자격 증명 참조 이름, 비밀이 아닌 계정 라벨.
+- **공급자 준비 상태:** `ready`, `needs_credentials`, `needs_attention`, `checking`, `disabled` 또는 `summarizeWorkspaceConnectionProviderReadiness()`를 통한 `not_configured`.
+- **소스 상태:** 앱-로컬로 구성된 소스, 커서, 동기화 상태 및 다음 작업.
+
+Brain의 소스 페이지는 참조 구현입니다. Brain 소스 레코드 옆에 재사용 가능한 작업 공간 연결 제공자를 표시하고 부여 상태를 `connected`, `granted`, `needs_grant` 또는 `not_connected`로 레이블 지정하고 제공자 상태를 준비됨, 누락된 키, 부여 필요, 복구 필요 또는 메타데이터만으로 표시합니다.
+
+### 재사용 가능한 커넥터 만들기
+
+새 제공업체가 여러 템플릿에서 작업해야 하는 경우:
+
+1. **공급자 메타데이터:** `@agent-native/core/connections`에서 공급자를 추가하거나 재사용합니다. 이는 안정적인 ID, 표시 레이블, 기능 목록, 권장 템플릿 사용 및 자격 증명 키 이름입니다.
+2. **작업 공간 연결:** 디스패치 또는 다른 작업 공간 설정 화면은 연결된 계정의 안전한 메타데이터, 상태, 범위, `credentialRefs` 및 `@agent-native/core/workspace-connections`를 통한 앱 부여를 저장합니다.
+3. **앱 로컬 소스:** Brain, Analytics, Mail 또는 기타 앱은 Slack 채널, GitHub 저장소, HubSpot 개체 필터, 동기화 커서 또는 폴링 흐름과 같이 자신이 소유한 앱별 선택 사항만 저장합니다.
+
+각 앱에 OAuth/토큰 저장소를 중복하지 마세요. 연결 기록에는 "이것은 Acme Slack이며 해당 토큰은 `SLACK_BOT_TOKEN`에 있습니다"라고 나와 있습니다. 앱 로컬 소스에 "Brain은 해당 Slack 연결에서 `#product` 및 `#dev-fusion`를 수집할 수 있습니다."라고 나와 있습니다.
+
+### 디스패치 제어 평면 설정
+
+Dispatch는 앱이 직접 호출할 수 있는 동일한 공유 저장소 기능을 작성하는 제어 평면 actions를 노출합니다.
+
+```ts
+// templates/dispatch/actions/upsert-workspace-connection.ts delegates to this.
+await upsertWorkspaceConnection({
+  id: "team-slack",
+  provider: "slack",
+  label: "Acme Slack",
+  accountId: "T012345",
+  accountLabel: "acme",
+  status: "connected",
+  scopes: ["channels:history", "groups:history"],
+  config: { teamDomain: "acme", preferredChannels: ["product", "dev-fusion"] },
+  credentialRefs: [
+    {
+      key: "SLACK_BOT_TOKEN",
+      scope: "org",
+      provider: "slack",
+      label: "Slack bot token",
+    },
+  ],
+});
+
+// Then grant the apps that should reuse the provider.
+await upsertWorkspaceConnectionGrant({
+  connectionId: "team-slack",
+  appId: "brain",
+});
+await upsertWorkspaceConnectionGrant({
+  connectionId: "team-slack",
+  appId: "analytics",
+});
+```
+
+동일한 범위에 있는 모든 앱에 연결을 사용할 수 있어야 하는 경우에만 `allowedApps: []`를 사용하세요. 프로덕션 설정에는 명시적 승인 행을 선호합니다.
+
+### 자격증명 확인
+
+앱 실행 코드는 활성 요청 범위의 자격 증명 모음을 통해 부여된 `credentialRefs`의 자격 증명 값을 확인합니다. Brain의 `source-credentials.ts`는 현재 참조 구현입니다. 공급자에 대한 작업 공간 연결을 나열하고, `getWorkspaceConnectionAppAccess`에서 `appId: "brain"`를 확인하고, 연결 수준 및 권한 부여 수준 자격 증명 참조를 병합하고, 일치하는 첫 번째 범위 지정 저장소 비밀을 읽습니다. 다른 앱은 `process.env`에 도달하는 대신 그 형태를 따라야 합니다.
+
+## 디자인 노트 {#design-notes}
+
+<details>
+<summary>리더 프로모션 정책 및 "한 번 연결하면 어디에서나 사용 가능" </summary>
+
+### 앱-로컬 경계
+
+공유 연결과 앱-로컬 소스 사이의 경계는 의도적인 것입니다. 오늘날 재사용할 수 있는 것은 공급자 ID, 자격 증명 참조 확인, 앱별 부여, 공급자 준비, 안전한 계정 메타데이터 및 정규화된 공급자-독자 계약입니다. 아직 일반적이지 않은 것은 대부분의 라이브 공급자 API 읽기, OAuth 흐름 소유권, 수집 커서, 소스 필터, 동기화 케이던스 및 도메인 해석입니다. 리더 구현이 명시적으로 공유로 승격되지 않는 한 워크플로를 소유한 앱에 유지됩니다.
+
+앱 소스 커넥터는 사용자/조직 소스 자격 증명에 대한 대체 수단으로 배포 수준 환경 변수를 읽어서는 안 됩니다. 환경 변수는 배포에 전역적이며 작업 공간 부여를 표현하지 않습니다.
+
+에이전트는 간단한 규칙을 따라야 합니다. 사용자가 Slack, GitHub, HubSpot, Gmail, Google Drive, Granola 또는 다른 공유 공급자 연결을 요청하는 경우 먼저 작업 공간 연결 카탈로그를 검사하세요. 공급자가 `connected`인 경우 이를 사용합니다. `needs_grant`인 경우 앱 부여를 요청하거나 수행합니다. `needs_credentials`인 경우 누락된 볼트 키를 요청하세요. 재사용 가능한 연결이 없는 경우에만 새 원시 키를 요청하세요.
+
+### "한 번 연결하면 어디에서나 사용 가능" 경로
+
+공급자 카탈로그와 보조금 저장소는 더 넓은 작업 공간 계층을 위한 기반입니다.
+
+- 공유 제공자 ID 및 기능 이름은 템플릿을 정렬된 상태로 유지합니다.
+- 작업 공간 수준 인벤토리는 Brain, Mail, Analytics, Dispatch 및 향후 앱 전반에 걸쳐 구성된 공급자를 표시할 수 있습니다.
+- 연결 행은 템플릿 관련 공급자 ID를 변경하지 않고도 계정 레이블, 상태, 허용된 앱, 자격 증명 참조 및 상태 확인을 기록합니다.
+- 행 부여를 통해 작업 공간 소유자는 한 번 연결한 다음 작업 공간에서 개별 앱을 채택할 때 개별 앱을 활성화할 수 있습니다.
+- 에이전트는 이미 연결되어 있는 제공업체와 권한이 부여된 앱을 파악하여 앱 간에 작업을 라우팅할 수 있습니다.
+- 통합 검색은 모든 앱의 커넥터 목록을 하드코딩하는 대신 `search`, `docs`, `messages`, `meetings`, `crm` 또는 `code` 기능을 갖춘 공급자를 요청할 수 있습니다.
+- 공급자별 리더, OAuth 새로 고침 흐름, 수집 체크포인트, 앱 소유 데이터 모델은 나중에 공유될 수 있지만 현재 작업 공간 연결에 의해 암시되지는 않습니다.
+
+경계를 엄격하게 유지하십시오. 제공자 메타데이터는 표시해도 안전합니다. 자격 증명 값은 저장소에 유지됩니다.
+
+</details>

package/corpus/core/docs/content/locales/ko-KR/workspace-management.md

@@ -0,0 +1,175 @@
+---
+title: "작업 공간 거버넌스"
+description: "브랜칭, CODEOWNERS, PR 검토 및 Dispatch가 Git 수준 거버넌스와 함께 런타임 거버넌스를 처리하는 방법"
+---
+
+# 작업 공간 거버넌스
+
+> **어떤 작업공간 문서인가요?** 이 페이지에서는 하나의 저장소에 있는 여러 앱의 내용을 검토, 승인 및 소유하는 **거버넌스**에 대해 다룹니다. 작업공간(사용자 정의 레이어)이 무엇인지에 대해서는 [Workspace](/docs/workspace)를 참조하세요. 배포 형태(하나의 단일 저장소, 많은 앱)는 [Multi-App Workspaces](/docs/multi-app-workspace)를 참조하세요.
+
+이 가이드에서는 분기 방법, 누가 무엇을 검토하는지, 코드 소유권을 설정하는 방법, Dispatch 제어 플레인이 거버넌스 모델에 어떻게 적합한지 등 에이전트 기반 작업 영역 실행의 운영 측면을 다룹니다.
+
+```an-diagram title="Two governance planes" summary="Git governs code; Dispatch governs runtime. They are complementary — don't replicate one inside the other."
+{
+  "html": "<div class=\"gov\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Git / GitHub</span><strong>Code governance</strong><div class=\"gov-list\"><span class=\"diagram-pill\">CODEOWNERS</span><span class=\"diagram-pill\">branch protection</span><span class=\"diagram-pill\">PR review</span><span class=\"diagram-pill\">git log / blame</span></div></div><div class=\"diagram-pill diagram-muted\">+</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Dispatch</span><strong>Runtime governance</strong><div class=\"gov-list\"><span class=\"diagram-pill\">vault secrets &amp; grants</span><span class=\"diagram-pill\">workspace resources</span><span class=\"diagram-pill\">agent profiles</span><span class=\"diagram-pill\">approvals &amp; audit</span></div></div></div>",
+  "css": ".gov{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.gov .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:240px}.gov .gov-list{display:flex;flex-wrap:wrap;gap:6px;margin-top:4px}"
+}
+```
+
+## 분기
+
+### 기능 분기
+
+모든 작업에 단기 기능 분기 사용:
+
+```
+main                         ← production
+├── feat/mail-filters        ← single-app change
+├── feat/core-oauth-refresh  ← framework change
+├── fix/analytics-chart      ← targeted bug fix
+└── feat/vault-encryption    ← dispatch/infra change
+```
+
+**명명 규칙:**
+
+- **단일 앱 변경:** `feat/<app>-<description>` 또는 `fix/<app>-<description>` — 예: `feat/mail-thread-search`, `fix/calendar-recurrence-parse`
+- **프레임워크 변경:** `feat/core-<description>` 또는 `fix/core-<description>` — 예: `feat/core-polling-v2`
+- **디스패치 변경 사항:** `feat/dispatch-<description>` — 예: `feat/dispatch-vault-policies`
+- **교차 앱 변경:** 프레임워크 변경에 템플릿 업데이트가 필요한 경우 하나의 분기에서 두 작업을 모두 수행하여 원자적으로 배송되도록 합니다.
+
+가지의 수명을 짧게 유지하세요. 수명이 긴 브랜치는 메인에서 분기되어 고통스러운 병합을 생성합니다. 특히 여러 팀이 매일 푸시하는 단일 저장소에서는 더욱 그렇습니다.
+
+### 비개발자 분기
+
+변경이 필요한 모든 사람이 git에 익숙하지는 않습니다. [Builder.io](https://www.builder.io)는 내부적으로 git 분기에 매핑되는 시각적 분기 모델을 지원합니다. 이는 개발 환경 없이 콘텐츠 및 복사 변경, 레이아웃 조정, 디자인 반복 및 A/B 테스트에 유용합니다.
+
+## 코드 소유권
+
+코드 거버넌스는 저장소 루트에 있는 소수의 파일로 구성됩니다.
+
+```an-file-tree title="Governance config in the repo"
+{
+  "entries": [
+    { "path": ".github/CODEOWNERS", "note": "Auto-assigns reviewers per changed path" },
+    { "path": ".github/labeler.yml", "note": "Auto-labels PRs by app" },
+    { "path": "pnpm-workspace.yaml", "note": "Workspace-level — broad review" },
+    { "path": "package.json", "note": "Workspace-level — platform team owns" }
+  ]
+}
+```
+
+GitHub의 CODEOWNERS 파일은 변경된 파일을 기반으로 검토자를 PR에 자동 할당합니다. 저장소 루트에 `.github/CODEOWNERS`를 생성합니다.
+
+```
+# Framework core — affects every app; platform team reviews all changes
+packages/core/                     @your-org/platform-team
+
+# Dispatch control plane — secrets, integrations, workspace resources
+templates/dispatch/                @your-org/platform-team
+
+# Per-app ownership — each team reviews their own app
+templates/mail/                    @your-org/mail-team
+templates/analytics/               @your-org/analytics-team
+templates/calendar/                @your-org/calendar-team
+# ... add an entry per app
+
+# Workspace-level config — broad review since it affects everyone
+.github/                           @your-org/platform-team
+package.json                       @your-org/platform-team
+pnpm-workspace.yaml                @your-org/platform-team
+```
+
+주요 팁: 개인이 아닌 GitHub 팀(`@org/team`)을 사용하세요. 프레임워크 및 디스패치 변경에는 항상 플랫폼 검토가 필요합니다. glob 구문과 다중 소유자 패턴은 [GitHub CODEOWNERS docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)를 참조하세요.
+
+필수 검토를 활성화하려면: 설정 → 지점 → `main`에 대한 지점 보호 → **병합 전 끌어오기 요청 필요** → **코드 소유자의 검토 필요**.
+
+## 홍보 라벨링
+
+`.github/labeler.yml`를 사용하여 앱별로 PR 자동 라벨 지정(발췌):
+
+```yaml
+app:mail:
+  - changed-files:
+      - any-glob-to-any-file: templates/mail/**
+app:analytics:
+  - changed-files:
+      - any-glob-to-any-file: templates/analytics/**
+core:
+  - changed-files:
+      - any-glob-to-any-file: packages/core/**
+```
+
+그런 다음 [actions/labeler](https://github.com/actions/labeler) 작업을 추가합니다. 전체 워크플로 YAML는 해당 저장소의 README를 참조하세요. PR을 열거나 업데이트하면 라벨이 자동으로 적용됩니다.
+
+## 홍보심사지침
+
+| 변경 유형                         | 리뷰하는 사람                     | 주의할 점                                                                       |
+| --------------------------------- | --------------------------------- | ------------------------------------------------------------------------------- |
+| **앱 전용** (`templates/<app>/`)  | 앱팀 소유                         | 도메인 정확성, 작업 스키마                                                      |
+| **프레임워크** (`packages/core/`) | 플랫폼 팀 + 영향을 받는 앱 팀 1개 | 급격한 변화, 성능, 이전 버전과의 호환성                                         |
+| **스키마 마이그레이션**           | 플랫폼 팀 + 수석 엔지니어         | 데이터 안전, 방언 불가지론(SQLite + Postgres)                                   |
+| **Actions**                       | 소유팀                            | Actions는 둘 다 에이전트 도구 AND HTTP 엔드포인트입니다. 두 각도에서 검토하세요 |
+| **크로스 앱 A2A**                 | 두 앱 팀                          | A2A 인터페이스를 변경하는 경우 호출자가 알아야 할 사항                          |
+| **금고/자원 파견**                | 플랫폼 팀                         | 비밀 액세스, 부여 범위, 누가 무엇을 얻습니까                                    |
+
+### 동시 에이전트 작업
+
+에이전트 기반 작업 공간에는 동일한 지점에서 동시에 작업하는 여러 AI 에이전트가 있는 경우가 많습니다. 이는 의도적으로 설계된 것입니다. 에이전트는 분기를 공유하고 독립적으로 푸시합니다.
+
+```an-callout
+{ "tone": "warning", "body": "**The later commit wins.** Two agents touching the same file won't conflict at commit time — the conflict surfaces at review. Run `pnpm run prep` (typecheck + test + format) before pushing, and don't revert changes you didn't make unless they're clearly broken." }
+```
+
+이 환경에서 PR을 검토할 때:
+
+- **변경하지 않은 변경 사항을 되돌리지 마세요** 명확하게 깨진 경우가 아니면
+- **파일은 동일한 PR에서 여러 에이전트에 의해 수정될 수 있습니다** — 이는 정상입니다.
+- **에이전트 변경 사항 간의 통합 문제를 파악하기 위해 푸시하기 전에 `pnpm run prep`**(유형 확인 + 테스트 + 형식)를 실행하세요.
+- **두 에이전트가 동일한 파일을 터치하는 경우** 나중에 커밋이 적용됩니다. 커밋 시점이 아닌 검토 시점에 충돌이 나타납니다.
+- **어떤 에이전트가 작성했는지에 관계없이 PR의 모든 코드에서 버그를 수정합니다.** PR은 전체적으로 검토됩니다.
+
+## 거버넌스로 파견
+
+[Dispatch](/docs/dispatch) 앱은 작업공간의 런타임 제어 평면입니다. 런타임 거버넌스를 통해 Git 수준 거버넌스를 보완합니다.
+
+| 우려                         | 힘내 / GitHub           | 파견                                          |
+| ---------------------------- | ----------------------- | --------------------------------------------- |
+| 코드를 변경할 수 있는 사람   | CODEOWNERS, 분기 보호   | —                                             |
+| 비밀에 액세스할 수 있는 사람 | —                       | Vault 정책, 권한 부여, 요청 워크플로          |
+| 상담원이 따라야 할 지침      | —                       | 전역 작업공간 리소스(AGENTS.md, 지침, skills) |
+| 공유되는 에이전트            | —                       | Workspace 에이전트 프로필                     |
+| 통합 인벤토리                | —                       | 작업 공간 연결 및 통합 카탈로그               |
+| 런타임 변경 승인             | —                       | 파견 승인 흐름                                |
+| 감사 추적                    | `git log` / `git blame` | Vault 감사 + 발송 감사 로그                   |
+| 메시징 및 라우팅             | —                       | Slack / 텔레그램 통합                         |
+
+**Git이 코드 거버넌스를 처리합니다. Dispatch는 런타임 거버넌스를 처리합니다.** Dispatch 내에서 git 워크플로를 복제하려고 시도하거나 그 반대의 경우도 마찬가지입니다.
+
+디스패치는 저장소 비밀, 재사용 가능한 작업 공간 연결, 작업 공간 리소스(skills, 지침, 에이전트 프로필, MCP 서버), 승인 및 감사 로그를 관리합니다. 공용 앱 경로 구성(`workspaceApp.audience` / `publicPaths` / `protectedPaths`)은 [Multi-App Workspaces — Public app routes](/docs/multi-app-workspace#deployment)를 참조하세요.
+
+리소스 모델 및 표준 경로는 [Workspace — Global resources](/docs/workspace#global-resources)를 참조하세요.
+
+## 설정 체크리스트
+
+새 작업 공간의 경우 `npx @agent-native/core@latest create`를 실행한 후:
+
+**깃 & GitHub:**
+
+- [ ] 앱별 팀 소유권으로 `.github/CODEOWNERS` 생성
+- [ ] 필수 코드 소유자 검토를 통해 `main`에서 분기 보호 활성화
+- [ ] 앱별 PR 자동 라벨 지정을 위해 `.github/labeler.yml` 추가
+- [ ] 각 앱 및 플랫폼 팀을 위한 GitHub 팀 만들기
+
+**배달:**
+
+- [ ] 저장소에 공유 비밀 추가(API 키, OAuth 자격 증명 등)
+- [ ] 기본 모든 앱 저장소 정책을 유지하거나 수동 앱별 부여로 전환
+- [ ] 저장소 비밀을 동기화하여 앱에 푸시
+- [ ] 공유 공급자 계정에 대해 재사용 가능한 작업 공간 연결을 등록한 다음
+      Brain, Analytics, Mail, Dispatch 등의 앱이 필요할 때만 부여
+      해당 계정
+- [ ] 리소스 페이지를 통해 작업 공간 전체 skills, 가드레일 지침 및 브랜드/회사 참조 리소스를 추가합니다. 전체 리소스 모델 표와 권장 스타터 팩은 [Workspace](/docs/workspace#global-resources)를 참조하세요.
+- [ ] 승인 정책 및 승인자 이메일 구성
+- [ ] 관리자 알림을 위한 SendGrid(`SENDGRID_API_KEY`, `SENDGRID_FROM_EMAIL`) 설정
+- [ ] 작업 공간 메시징을 위해 Slack 또는 Telegram을 연결하세요
+- [ ] 공유 MCP 서버 구성 - 모든 앱 또는 선택된 앱 부여를 위해 Dispatch에 `mcp-servers/<name>.json` 작업 공간 리소스를 추가합니다. 낮은 수준의 배포에는 `mcp.config.json` 또는 [MCP hub mode](/docs/mcp-clients#hub)를 사용하세요.