@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,312 @@
+---
+title: "다중 앱 작업 공간"
+description: "공유 인증, RBAC, 지침, skills, 구성 요소 및 자격 증명을 사용하여 하나의 단일 저장소에서 여러 에이전트 기본 앱을 호스팅합니다."
+---
+
+# 다중 앱 작업 공간
+
+> **어떤 작업공간 문서입니까?** 이 페이지에서는 하나의 단일 저장소, 여러 앱, 공유 인증 및 통합 배포 등 **배포 형태**를 다룹니다. 작업공간이 무엇인지에 대해서는(사용자 정의 레이어: `AGENTS.md`, `LEARNINGS.md`, 개인 메모리, skills, 사용자 정의 에이전트) [Workspace](/docs/workspace)를 참조하세요. 거버넌스(누가 무엇을 검토하고, 승인하고, 소유하는지)에 대해서는 [Workspace Governance](/docs/workspace-management)를 참조하세요.
+
+내부 도구의 바이브 코딩에 오후가 걸리면 한시에 멈추지 않습니다. 팀은 CRM, 지원 받은 편지함, 대시보드, 운영 콘솔(각각 독립적으로 스캐폴드된 10개의 작은 앱)로 끝납니다. 모든 항목에서 무언가를 변경해야 할 때까지는 좋습니다.
+
+이 시점에서 모든 앱에는 자체 `AGENTS.md`, 자체 인증 플러그인, 자체 복사하여 붙여넣은 레이아웃 구성 요소, 자체 하드 코딩된 Slack 토큰, "조직"이 무엇인지에 대한 자체 아이디어가 있습니다. 규정 준수 규칙 변경은 10개의 PR을 의미합니다. API 키 순환은 10번의 재배포를 의미합니다. 브랜드 새로 고침은 10개의 서로 다른 헤더가 동기화되지 않음을 의미합니다. 구축을 쉽게 만들었던 것이 이제 관리를 어렵게 만들고 있습니다.
+
+**다중 앱 작업 공간** 패턴은 에이전트 기반이 이 문제를 해결하는 방법입니다. 비공개 `packages/shared` 패키지와 함께 하나의 단일 저장소에 모든 앱을 호스팅합니다. 프레임워크는 공통 기본값을 소유합니다. `packages/shared`는 작업 공간에 맞게 실제로 사용자 정의된 코드, 지침, skills, 구성 요소 또는 플러그인 재정의에만 사용됩니다. 각 앱은 소수의 화면과 actions로 축소되어 고유하게 만들어집니다.
+
+## 공유되는 내용 {#what-gets-shared}
+
+조직의 모든 앱이 동의해야 하는 모든 항목은 `packages/shared`에 존재할 수 있습니다.
+
+| 공유된 것                | 살아있는 곳                                                                                  |
+| ------------------------ | -------------------------------------------------------------------------------------------- |
+| 인증 / SSO 재정의        | `src/server/index.ts`에서 `authPlugin` 내보내기                                              |
+| 조직 / RBAC 규칙         | `authPlugin`로 선택적으로 래핑된 더 나은 인증 조직                                           |
+| 상담원 채팅 재정의       | `src/server/index.ts`에서 `agentChatPlugin` 내보내기                                         |
+| 엔터프라이즈 상담원 지침 | `AGENTS.md`                                                                                  |
+| skills 요원              | `.agents/skills/<skill-name>/SKILL.md`                                                       |
+| 공유 에이전트 actions    | `actions/*.ts`                                                                               |
+| 공유 React 구성요소      | `src/client/index.ts`에서 내보내기                                                           |
+| 디자인 토큰/브랜드       | 공유 CSS 파일을 추가하고 각 앱에서 가져오기                                                  |
+| 공유된 API 자격 증명     | 프레임워크 범위의 자격 증명을 선호합니다. 네임스페이스가 필요한 경우에만 도우미를 추가하세요 |
+
+각 개별 앱은 경로, 대시보드, 보기, 도메인별 actions 등 *단순한 화면 집합*이 됩니다. 실제 작업 공간 사용자 정의를 추가할 때까지 나머지는 프레임워크 기본값에 따릅니다.
+
+앱이 다른 자사 앱을 사용하려는 경우에도 동일한 경계가 적용됩니다. 이메일, 캘린더, 분석 및 회사 메모리 컨텍스트가 필요한 새로운 작업 공간 대시보드는 기존 메일, 캘린더, 분석 및 Brain 앱을 링크 또는 A2A를 통해 연결된 이웃으로 사용해야 합니다. 해당 템플릿을 복제하거나, 템플릿을 중첩하는 래퍼 앱을 생성하거나, 단지 데이터나 에이전트에 액세스하기 위해 내부에 하위 앱을 스캐폴드해서는 안 됩니다. 해당 앱을 명시적으로 사용자 정의하려는 경우에만 복사본을 포크하거나 스캐폴드하세요.
+
+## 시작하기 {#getting-started}
+
+작업공간은 에이전트 기반 프로젝트의 기본 형태입니다. 다음을 갖춘 비계:
+
+```bash
+npx @agent-native/core@latest create my-company-platform
+```
+
+CLI는 모든 자사 템플릿의 다중 선택 선택기를 표시합니다. 예를 들어 메일 + 달력 + 양식 등 원하는 만큼 선택하면 인증 및 데이터베이스 기본값을 공유하는 동일한 작업 공간에 모두 스캐폴딩됩니다.
+
+개인 공유 패키지가 포함된 pnpm 모노레포, 작업 영역 검색을 연결하는 루트 `package.json`, 공유 `.env` 및 선택한 앱당 하나의 하위 디렉터리를 얻습니다.
+
+```an-file-tree title="A scaffolded workspace"
+{
+  "entries": [
+    { "path": "package.json", "note": "declares agent-native.workspaceCore" },
+    { "path": "pnpm-workspace.yaml", "note": "packages: [\"packages/*\", \"apps/*\"]" },
+    { "path": ".env.example", "note": "shared ANTHROPIC_API_KEY, A2A_SECRET, DATABASE_URL, ..." },
+    { "path": "packages/shared/", "note": "@my-company-platform/shared" },
+    { "path": "packages/shared/src/server/", "note": "plugin overrides only when needed" },
+    { "path": "packages/shared/src/client/", "note": "shared React code only when needed" },
+    { "path": "packages/shared/AGENTS.md", "note": "workspace-wide instructions" },
+    { "path": "apps/mail/" },
+    { "path": "apps/calendar/" },
+    { "path": "apps/forms/" }
+  ]
+}
+```
+
+그런 다음 부팅하십시오.
+
+```bash
+cd my-company-platform
+cp .env.example .env             # fill in ANTHROPIC_API_KEY, BETTER_AUTH_SECRET, ...
+pnpm install
+pnpm dev                         # opens Dispatch; other apps start on first visit
+```
+
+모든 앱은 로그인 방법, 동일한 데이터베이스 공유 방법, 작업 공간 `AGENTS.md` 로드 방법을 이미 알고 있습니다. 그 중 어떤 것도 연결하지 않았습니다. 프레임워크는 루트 `package.json`의 `agent-native.workspaceCore` 필드를 통해 공유 패키지를 자동 검색했습니다.
+
+```json
+{
+  "name": "my-company-platform",
+  "agent-native": {
+    "workspaceCore": "@my-company-platform/shared"
+  }
+}
+```
+
+## 다른 앱 추가 {#adding-a-new-app}
+
+작업공간 내부 어디에서나:
+
+```bash
+npx @agent-native/core@latest add-app
+```
+
+CLI는 이미 설치한 앱을 필터링하여 템플릿 선택기를 다시 표시합니다. 하나 이상을 선택하면 `apps/` 아래에 비계가 설치됩니다. 비대화형 변형:
+
+```bash
+npx @agent-native/core@latest add-app crm --template content
+```
+
+모든 자사 템플릿은 작업 공간 앱으로 작동합니다. CLI는 공유 패키지를 dep으로 추가하고 `workspace:*` 참조를 확인하는 템플릿에서 작은 **workspacify** 변환을 실행합니다. 유지 관리할 병렬 "작업 공간 앱" 스캐폴드가 없습니다.
+
+```bash
+pnpm install                     # at the workspace root
+pnpm dev
+```
+
+그렇습니다. 새 앱에는 다른 모든 앱과 동일한 로그인 및 작업 공간 지침이 있습니다. 작업 공간에 실제로 필요한 경우에만 공유 브랜드, actions 또는 자격 증명을 추가하세요.
+
+## 무엇을 재정의하는지 {#layering}
+
+작업 영역 내의 에이전트 기반 앱은 다음 순서로 세 위치에서 교차 동작을 해결합니다.
+
+1. **앱 로컬** — `apps/<name>/` 내부 파일(가장 높은 우선순위)
+2. **작업 공간 공유** — `packages/shared/` 내부 파일(공유 중간 계층)
+3. **프레임워크 기본값** — `@agent-native/core`(최저)
+
+병합은 파일 이름별로 이루어집니다. 앱이 업스트림에도 존재하는 로컬 파일을 제공하는 경우 로컬 파일이 우선합니다. 그렇지 않은 경우 작업공간 공유 버전이 적용됩니다. 공유가 둘 중 하나를 제공하지 않으면 프레임워크 기본값이 시작됩니다. 이는 플러그인 skills, actions 및 `AGENTS.md`에 적용됩니다.
+
+```an-diagram title="Three layers, merged by file name" summary="Each app resolves plugins, skills, actions, and AGENTS.md from app-local first, then the shared package, then the framework default."
+{
+  "html": "<div class=\"layer\"><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">1 &middot; App local</span><small class=\"diagram-muted\"><code>apps/&lt;name&gt;/</code> &mdash; highest priority</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">2 &middot; Workspace shared</span><small class=\"diagram-muted\"><code>packages/shared/</code> &mdash; the mid-layer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">3 &middot; Framework default</span><small class=\"diagram-muted\"><code>@agent-native/core</code> &mdash; lowest</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box ok\">first match wins</div></div>",
+  "css": ".layer{display:flex;flex-direction:column;align-items:center;gap:6px}.layer .diagram-card{display:flex;flex-direction:column;gap:3px;padding:12px 16px;width:320px}.layer .diagram-arrow{font-size:18px;line-height:1}.layer .diagram-box{margin-top:2px}"
+}
+```
+
+한 앱에 다른 것이 필요한 경우 로컬 파일을 삭제하세요.
+
+| 무시할 사항            | 앱 내부에서 생성할 파일                            |
+| ---------------------- | -------------------------------------------------- |
+| 인증 플러그인          | `apps/<name>/server/plugins/auth.ts`               |
+| 에이전트 채팅 플러그인 | `apps/<name>/server/plugins/agent-chat.ts`         |
+| 특정 스킬              | `apps/<name>/.agents/skills/<skill-name>/SKILL.md` |
+| 특정 작업              | `apps/<name>/actions/<action-name>.ts`             |
+| 추가 상담사 안내       | `apps/<name>/AGENTS.md`(작업공간 1과 병합)         |
+
+배선도 없고 구성도 없습니다. 파일을 생성하면 적용됩니다.
+
+## 공유 행동 편집 {#editing-shared-behavior}
+
+사용자 정의한 모든 크로스커팅이 `packages/shared/`에 저장됩니다. `src/server/index.ts`에서 `authPlugin`를 내보내면 모든 앱이 다음 개발 재로드 시 이를 선택합니다. `.agents/skills/` 아래에 스킬을 추가하면 모든 앱의 에이전트가 이를 볼 수 있습니다. `actions/`에 작업을 추가하면 모든 앱의 에이전트가 이를 호출할 수 있습니다.
+
+공유 패키지는 `workspace:*` 종속성이므로 pnpm는 이를 각 앱의 `node_modules/`에 심볼릭 링크합니다. 빌드하거나 게시할 필요가 없습니다. 앱은 빌드 시 필요한 모든 것을 번들로 묶습니다.
+
+## 런타임 글로벌 리소스 {#runtime-global-resources}
+
+저장소와 함께 제공되어야 하는 코드 수준 기본값(플러그인, 공유 actions, 공유 React 코드, 파일 시스템 `AGENTS.md` 및 파일 시스템 skills)에는 `packages/shared`를 사용합니다. 관리자가 코드 변경 없이 관리하려는 런타임 편집 가능 전역 컨텍스트에 Dispatch 작업공간 리소스를 사용하세요.
+
+디스패치 리소스의 범위는 **모든 앱**(모든 앱이 런타임 시 복사 또는 동기화 단계 없이 상속됨) 또는 **선택한 앱**(앱별 컨텍스트에 대해 앱별로 부여됨)으로 지정됩니다. 전체 리소스 모델 테이블, 경로 규칙 및 권장 스타터 팩은 [Workspace](/docs/workspace#global-resources)를 참조하세요.
+
+## 인증 및 RBAC {#auth-and-rbac}
+
+모든 에이전트 기반 앱에는 이미 [Better Auth](/docs/authentication)와 프레임워크의 내장 조직 시스템이 함께 제공됩니다. 작업 공간에서는 동일한 데이터베이스가 지원되는 모든 앱에서 무료로 얻을 수 있습니다. 전체 다중 테넌시 모델(조직, 역할, 데이터 격리)은 [Multi-Tenancy](/docs/multi-tenancy)를 참조하세요.
+
+기업별 규칙(허용 목록 도메인, SSO 시행, 추가 역할 확인)의 경우 `packages/shared/src/server/index.ts`에서 `authPlugin`를 내보냅니다. 이제 작업 공간의 모든 앱이 이러한 규칙을 시행합니다.
+
+활성 조직은 `session.orgId` → `AGENT_ORG_ID` → SQL 행 범위 지정과 같이 자동으로 흐르므로 `org_id`로 태그가 지정된 데이터는 에이전트뿐 아니라 다른 조직에서도 볼 수 없습니다. 전체 모델을 보려면 [Security & Data Scoping](/docs/security)를 참조하세요.
+
+## 공유 MCP 서버 {#shared-mcp}
+
+작업 공간 앱 전체에서 MCP 서버를 공유하기 위한 권장 옵션(선호도 순):
+
+1. **작업 공간 MCP 리소스 디스패치** — **모든 앱** 범위의 디스패치에 `mcp-servers/<name>.json` 리소스를 추가합니다. 작업 공간의 모든 앱은 파일 편집이나 재배포 없이 런타임 시 MCP 서버를 상속합니다. 서버가 앱별인 경우에만 선택한 앱에 부여합니다. 토큰은 Dispatch 저장소에 있습니다. `${keys.NAME}`를 사용하여 JSON 리소스에서 참조하세요.
+
+2. **루트 `mcp.config.json`** — 작업 공간 루트에 파일을 드롭하면 작업 공간의 모든 앱이 동일한 MCP 서버에 연결됩니다. 개별 앱은 자체 `mcp.config.json`로 재정의할 수 있습니다(앱 루트 승리). 사용자별 저장소 자격 증명이 필요하지 않은 로컬/파일 시스템 MCP 서버(`@modelcontextprotocol/server-filesystem`, `claude-in-chrome`, Playwright)에 이 기능을 사용하세요.
+
+3. **UI 설정(개인/조직 범위)** — 원격 HTTP MCP 서버의 경우 사용자는 개인 또는 팀(조직) 범위의 UI 설정에서 이를 추가할 수 있습니다. — 파일 편집이 없으며 실행 중인 에이전트에 핫 다시 로드됩니다.
+
+구성 스키마, 우선순위 규칙 및 허브 설정은 [MCP Clients](/docs/mcp-clients)를 참조하세요.
+
+## 공유 환경 변수 {#shared-env}
+
+작업공간 루트 `.env`는 모든 앱에 자동으로 로드됩니다. 공유 키(`ANTHROPIC_API_KEY`, `A2A_SECRET`, `BETTER_AUTH_SECRET`, `DATABASE_URL`, `BUILDER_PRIVATE_KEY` 등)를 루트에 한 번만 넣으면 모든 앱이 이를 선택합니다. 앱별 재정의는 `apps/<name>/.env`에 들어가 충돌 시 승리합니다.
+
+런타임 앱 자격 증명의 경우 `.env` 파일을 직접 편집하는 것보다 Dispatch Vault를 선호합니다. 볼트는 기본적으로 모든 앱 액세스로 설정되어 있으므로 저장된 모든 볼트 키는 모든 작업 공간 앱에서 사용할 수 있으며 `sync-vault-to-app`로 푸시할 수 있습니다. 앱에 명시적인 키별 부여가 필요한 경우에만 Vault를 수동 모드로 전환하세요.
+
+```text
+my-company-platform/
+├── .env                           # shared: ANTHROPIC_API_KEY=... , A2A_SECRET=... , ...
+└── apps/
+    └── mail/
+        └── .env                   # optional overrides just for mail
+```
+
+몇 가지 온보딩 흐름은 기본적으로 작업공간을 인식합니다.
+
+- **Builder `/cli-auth`**: 모든 앱에서 "Builder 연결"을 클릭하면 `BUILDER_PRIVATE_KEY`와 친구들이 **작업 공간 루트** `.env`에 기록되므로 모든 앱이 동시에 브라우저 액세스 권한을 얻게 됩니다.
+- **Env-vars 설정 경로** (`POST /_agent-native/env-vars`): 작업 공간 내부에 있을 때 기본적으로 작업 공간 루트 `.env`를 작성합니다. 하나의 앱을 재정의하려면 본문에 `scope: "app"`를 전달하세요.
+
+## 공유 자격 증명 {#shared-credentials}
+
+동일한 작업 공간에 있는 앱은 기본적으로 동일한 `DATABASE_URL`를 가리키므로 프레임워크 자격 증명 저장소는 앱별 구성 없이 모든 앱에서 자격 증명을 사용할 수 있도록 할 수 있습니다. `@agent-native/core/credentials`를 직접 사용하거나 작업 공간에서 더 엄격한 명명 규칙을 원하는 경우 `packages/shared`에 씬 도우미를 추가하세요.
+
+## 공유 디자인 토큰 {#design-tokens}
+
+프레임워크는 Tailwind v4에 있습니다. 작업 공간에 공유할 실제 브랜드 토큰이 있는 경우에만 공유 CSS 파일을 `packages/shared`에 추가한 다음 각 앱의 `app/global.css`에서 가져옵니다.
+
+```css
+@import "tailwindcss";
+@import "@my-company-platform/shared/styles/tokens.css";
+@source "./**/*.{ts,tsx}";
+
+:root {
+  --background: 0 0% 100%; /* ...brand tokens... */
+}
+.dark {
+  --background: 220 6% 6%; /* ... */
+}
+```
+
+브랜드 색상, 타이포그래피, 간격 척도 및 모든 공유 구성 요소 클래스가 하나의 CSS 파일에 포함될 수 있습니다. `packages/shared`에서 업데이트하면 모든 앱이 다음 빌드에서 브랜드가 변경됩니다.
+
+## 배포 {#deployment}
+
+두 가지 옵션이 있습니다: **통합 배포**(작업 영역의 기본값) 또는 앱별 독립 배포.
+
+### 통합 배포(권장)
+
+하나의 명령은 작업 공간의 모든 앱을 빌드하고 앱당 하나의 경로, 단일 원본 뒤에 전달합니다.
+
+```bash
+npx @agent-native/core@latest deploy
+# https://your-agents.com/mail/*       → apps/mail
+# https://your-agents.com/calendar/*   → apps/calendar
+# https://your-agents.com/forms/*      → apps/forms
+```
+
+각 앱은 `APP_BASE_PATH=/<name>` 및 `VITE_APP_BASE_PATH=/<name>`로 제작되었으며 선택한 Nitro 사전 설정을 통해 방출됩니다. Cloudflare Pages는 기본 사전 설정이며 `dist/_worker.js` 및 `_routes.json`의 디스패처 작업자를 사용합니다. Netlify는 `npx @agent-native/core@latest deploy --preset netlify`에서 지원됩니다. `.netlify/functions-internal/<app>-server`에서 앱 기능을 내보내고 정적 자산을 강제로 적용하지 않는 리디렉션을 생성하여 CDN가 파일을 먼저 제공합니다. Vercel은 `npx @agent-native/core@latest deploy --preset vercel`에서 지원됩니다. Vercel의 빌드 출력 API를 사용하여 루트 `.vercel/output` 번들을 작성합니다.
+
+```an-diagram title="Unified deploy: one origin, one path per app" summary="Every app ships behind a single origin, so login sessions and cross-app A2A are free."
+{
+  "html": "<div class=\"deploy\"><div class=\"diagram-box accent\">your-agents.com<br><small class=\"diagram-muted\">one DNS record &middot; one cert &middot; one CDN</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"deploy-apps\"><div class=\"diagram-box\">/mail/*</div><div class=\"diagram-box\">/calendar/*</div><div class=\"diagram-box\">/forms/*</div></div><div class=\"diagram-pill ok\">shared login cookie on the apex &bull; same-origin A2A, no CORS</div></div>",
+  "css": ".deploy{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.deploy .deploy-apps{display:flex;flex-direction:column;gap:8px}.deploy .diagram-arrow{font-size:24px}.deploy .diagram-pill{flex-basis:100%}"
+}
+```
+
+**동일한 출처**에 있다는 것이 진정한 보상이 되는 곳입니다:
+
+- **공유 로그인 세션.** Better Auth는 apex 도메인에 쿠키를 설정하므로 모든 앱에 로그인하면 모든 앱에 로그인됩니다. 도메인 간 SSO 댄스는 없습니다.
+- **Zero-config 교차 앱 A2A.** `@mail` 태깅 `@calendar`는 동일한 출처 가져오기가 됩니다. 즉, CORS가 없고 형제 간 JWT 서명이 없습니다. 외부 A2A는 오늘날에도 여전히 JWT를 사용합니다.
+- **DNS 레코드 1개, 인증서 1개, CDN 캐시 1개.**
+
+`dist/` 출력 게시:
+
+```bash
+wrangler pages deploy dist
+```
+
+넷리파이의 경우:
+
+```bash
+npx @agent-native/core@latest deploy --preset netlify --build-only
+```
+
+Vercel Git 배포의 경우 빌드 명령을 다음과 같이 설정합니다.
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel --build-only
+```
+
+### 공개 앱 경로
+
+Workspace 앱은 기본적으로 내부용입니다. 로그인 전용 관리 페이지가 있는 공개 사이트의 경우 공개 대상을 설정하고 해당 앱의 `package.json`에서 관리 접두사를 보호하세요.
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "audience": "public",
+      "protectedPaths": ["/admin"]
+    }
+  }
+}
+```
+
+공개 페이지가 몇 개 있는 대부분의 내부 앱의 경우 대상 내부 및 목록 페이지 접두사를 그대로 둡니다.
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "publicPaths": ["/", "/share"]
+    }
+  }
+}
+```
+
+이러한 설정은 읽기 전용 페이지 탐색에만 영향을 미칩니다. 프레임워크 도구, 상담원 채팅, A2A, Vault 액세스 및 임의 API는 앱이 `createAuthPlugin({ publicPaths: [...] })`로 공개 접두사를 명시적으로 선언하지 않는 한 인증된 상태를 유지합니다.
+
+### 앱별 독립적 배포
+
+자체 도메인(`mail.company.com`, `calendar.company.com`)에 있는 각 앱을 선호하시나요? 작업 공간의 모든 앱은 여전히 ​​독립적으로 배포 가능합니다. `cd apps/mail && npx @agent-native/core@latest build`는 ​​독립형 스캐폴드처럼 정확하게 작동합니다. 그런 다음 크로스 앱 A2A는 공유 `A2A_SECRET`를 사용하여 표준 JWT 서명 경로를 통과합니다. 별도로 배포된 앱 간의 도메인 간 SSO는 Dispatch를 허브로 사용하는 ID 페더레이션에 의해 처리됩니다. [Cross-App SSO](/docs/cross-app-sso)를 참조하세요. 통합된 단일 원본 배포를 사용하면 필요하지 않습니다.
+
+### 공유 데이터베이스, 공유 자격 증명
+
+무엇을 선택하든 모든 앱이 동일한 `DATABASE_URL`를 가리키도록 하여 즉시 앱 간 상태를 확인하세요. 사용자 계정 한 세트, 조직 한 세트, 공유 설정 한 세트. 각 앱에 자체 데이터베이스가 있는 경우 작업 공간 패턴은 계속 작동합니다. 공유 상태 스토리가 손실됩니다.
+
+공유 패키지 자체는 독립형으로 배포되지 않습니다. pnpm가 각 앱의 `node_modules/`에 심볼릭 링크되는 `workspace:*` dep이므로 모든 앱은 빌드 시 필요한 모든 것을 투명하게 번들링합니다.
+
+## 지원 범위 외(현재) {#out-of-scope}
+
+작업 공간 패턴은 의도적으로 좁습니다. 의도적으로 아직 처리하지 않는 몇 가지 사항:
+
+- **암호화된 자격 증명 저장소.** 런타임 앱 자격 증명에는 Dispatch 저장소를 선호합니다([Shared environment variables](#shared-env) 참조). Vault가 아닌 대체 경로(프레임워크 `settings` 테이블에 직접 작성된 공유 자격 증명)는 현재 이를 일반 텍스트로 저장하므로 이에 의존할 때는 책임감 있게 교체하세요.
+- **비공개 npm에 공유 코드 게시.** 공유 패키지는 `workspace:*` 전용입니다. 개인 레지스트리를 통한 다중 저장소 공유는 가능하지만 스캐폴딩되지는 않습니다.
+- **독립적인 구성 요소 라이브러리.** `packages/shared`는 _당신이_ 공유 구성 요소를 넣는 곳입니다. 프레임워크는 shadcn/ui 또는 다른 시스템을 해당 슬롯에 강제로 삽입하지 않습니다.
+
+## 참조 {#see-also}
+
+- [Workspace](/docs/workspace) — 작업 공간의 모든 앱이 공유하는 사용자 정의 레이어(`AGENTS.md`, `LEARNINGS.md`, 개인 메모리, skills, 사용자 정의 에이전트)
+- [Workspace Governance](/docs/workspace-management) — 하나의 저장소에 있는 여러 앱에 대한 분기, CODEOWNERS, PR 검토.
+- [Multi-Tenancy](/docs/multi-tenancy) — 조직, 역할 및 조직별 데이터 격리.
+- [Cross-App SSO](/docs/cross-app-sso) — 별도 도메인 배포를 위한 ID 페더레이션.
+- [Dispatch](/docs/dispatch) — 일반적으로 비밀 저장소, 통합 카탈로그 및 승인 허브로서 다중 앱 작업 공간 내에 있는 런타임 제어 플레인

package/corpus/core/docs/content/locales/ko-KR/multi-tenancy.md

@@ -0,0 +1,52 @@
+---
+title: "다중 테넌시"
+description: "모든 에이전트 기반 앱은 구성이 필요 없는 조직, 팀 구성원, 역할, 조직별 데이터 격리 등 즉시 사용 가능한 멀티 테넌트입니다."
+---
+
+# 다중 테넌시
+
+모든 에이전트 기반 앱은 기본적으로 다중 테넌트입니다. 조직, 팀 구성원, 역할 기반 액세스 및 조직별 데이터 격리가 구성 없이 프레임워크에 내장되어 있습니다.
+
+## 무료로 얻는 것 {#free}
+
+새로운 `npx @agent-native/core@latest create` 비계에는 이미 다음이 포함되어 있습니다:
+
+- **사용자 등록 및 로그인** — [Authentication](/docs/authentication)를 참조하세요.
+- **조직** — 사용자는 조직을 만들고 이메일로 구성원을 초대합니다. 각 조직은 완전히 격리된 테넌트입니다.
+- **역할** — 모든 구성원은 `owner`, `admin` 또는 `member`입니다. actions는 인증을 위한 역할을 확인할 수 있습니다.
+- **조직 전환** — 세션은 활성 조직(`session.orgId`)을 추적하고 이를 전환하면 사용자와 상담원이 보는 데이터가 변경됩니다.
+- **조직별 데이터 격리** — 모든 쿼리는 자동으로 활성 조직으로 범위가 지정됩니다.
+
+CRM, 프로젝트 추적기, 지원 받은 편지함 또는 모든 팀 도구에 대한 에이전트 기반을 평가하는 경우 다중 테넌트 기반이 이미 존재합니다. 모든 자사 템플릿은 다중 테넌트입니다. 목록은 [Cloneable SaaS templates](/docs/cloneable-saas)를 참조하세요.
+
+```an-diagram title="Org membership and isolation" summary="Users join organizations as owner/admin/member. Every ownable row carries the org_id of the tenant that owns it, and no row leaks across the boundary."
+{
+  "html": "<div class=\"mt-grid\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Org A</span><small class=\"diagram-muted\">members: alice (owner), bob (member)</small><div class=\"diagram-box\">rows where org_id = A</div></div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Org B</span><small class=\"diagram-muted\">members: carol (owner)</small><div class=\"diagram-box\">rows where org_id = B</div></div></div><div class=\"mt-wall\" aria-hidden=\"true\"><span class=\"diagram-pill warn\">no cross-org reads</span></div>",
+  "css": ".mt-grid{display:flex;gap:16px;flex-wrap:wrap}.mt-grid .diagram-card{display:flex;flex-direction:column;gap:8px;padding:14px 16px;flex:1;min-width:200px}.mt-wall{display:flex;justify-content:center;margin-top:12px}"
+}
+```
+
+## 조직 전환기 UI {#org-switcher}
+
+조직 전환기와 회원 UI는 추가 코드 없이 모든 템플릿을 렌더링합니다. 이들은 `/_agent-native/org/*` 아래에서 핵심 조직 REST 경로를 구동합니다(조직 생성, 조직 전환, 구성원 목록/초대/제거, 역할 변경, 허용된 이메일 도메인 설정). 사용자는 전환기에서 활성 조직을 선택합니다. 회원 패널은 초대 및 역할 변경을 처리합니다.
+
+이것은 Better Auth의 조직 플러그인(의도적으로 등록되지 않음)이 아닌 프레임워크 자체 `org/` 모듈입니다. 전체 조직 관리 표면(`createOrganization`, REST 경로 및 `invite-member`와 같은 템플릿 작성 `defineAction` 래퍼)은 [Authentication → Organizations](/docs/authentication#organizations)에 문서화되어 있습니다.
+
+## 격리 작동 방식 {#isolation}
+
+테넌트 데이터는 `org_id` 열(`ownableColumns()`에 의해 추가됨)로 격리되며 프레임워크는 모든 쿼리 범위를 자동으로 활성 조직(`session.orgId → AGENT_ORG_ID → SQL`)으로 지정합니다. 사용자가 조직을 전환하면 UI, actions 및 에이전트는 모두 해당 조직의 데이터만 볼 수 있습니다. 에이전트는 사용자가 구성원이 아닌 조직의 데이터에 접근할 수 없습니다.
+
+```an-diagram title="From session to scoped SQL" summary="The active org on the session becomes AGENT_ORG_ID, which the framework folds into the WHERE clause of every query."
+{
+  "html": "<div class=\"mt-pipe\"><div class=\"diagram-node\">session.orgId<br><small class=\"diagram-muted\">active org on session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">AGENT_ORG_ID<br><small class=\"diagram-muted\">request context</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">SQL row scoping<br><small class=\"diagram-muted\">WHERE owner_email = ? AND org_id = ?</small></div></div>",
+  "css": ".mt-pipe{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.mt-pipe .diagram-node{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.mt-pipe .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+이것은 사용자별 범위 지정에 사용되는 것과 동일한 파이프라인입니다. SQL 수준 메커니즘, `ownableColumns()` 계약 및 `accessFilter` / `resolveAccess` / `assertAccess` 가드에 대해서는 범위 지정 파이프라인을 위한 단일 정보 소스인 [Security → Data Scoping](/docs/security#data-scoping)를 참조하세요.
+
+## 관련 문서 {#related}
+
+- [Authentication](/docs/authentication#organizations) — 세션, 소셜 제공자 및 조직 관리 표면
+- [Security → Data Scoping](/docs/security#data-scoping) — SQL 수준 격리, `ownableColumns()` 계약 및 액세스 가드
+- [Multi-App Workspace](/docs/multi-app-workspace) — 공유 인증 및 RBAC를 사용하여 하나의 단일 저장소에서 여러 에이전트 기반 앱 호스팅