docs(readme): README를 한국어로 정리한다

README.md

@@ -1,68 +1,48 @@
 # nexo
 
-`nexo` is a Flutter messaging and notification package workspace. The main
-deliverable is `packages/messaging_flutter`: a reusable package that lets many
-Flutter apps integrate messaging and push-notification behavior without each app
-reimplementing the same native runtime. It is intended to be a shared messaging
-layer for sibling products such as IOP, NomadCode, and ALT when they need
-Mattermost-compatible messaging behavior without inheriting the full Mattermost
-product shape.
+`nexo`는 여러 Flutter 앱이 메시징과 푸시 알림 기능을 공통으로 사용할 수 있게 만드는 패키지 워크스페이스다. 핵심 산출물은 `packages/messaging_flutter`이며, 각 앱이 네이티브 메시징/푸시 런타임을 다시 구현하지 않고도 같은 기반을 소비할 수 있게 한다.
 
-Mattermost upstream repositories are kept as references around the package:
-`apps/mattermost` for the original Mattermost app, `services/core` for the
-server, and `services/push-proxy` for the push server. This repository does not
-contain a dedicated nexo product app, and it does not aim to become a broad
-Mattermost fork. Mattermost snapshots are kept as upstream baselines and
-validation references so Nexo-specific customization can stay in the plugin,
-compose/runtime wrappers, docs, or small explicit patches.
+이 패키지는 여러 소비 제품이 Mattermost 호환 메시징 동작은 필요하지만 Mattermost의 전체 제품 형태를 그대로 물려받고 싶지는 않을 때 쓰는 공통 메시징 계층이다.
 
-## Name
+Mattermost 업스트림 저장소는 이 패키지 주변의 기준선과 검증 참조로 둔다. `apps/mattermost`는 원래 Mattermost 앱, `services/core`는 Mattermost 서버, `services/push-proxy`는 Mattermost 푸시 서버 스냅샷이다. 이 저장소는 별도의 nexo 제품 앱을 담지 않으며, 넓은 Mattermost 포크가 되는 것도 목표가 아니다. Nexo 전용 커스터마이징은 가능한 한 플러그인, compose/런타임 래퍼, 문서, 작고 명시적인 패치에 둔다.
 
-`nexo` comes from `nexus`: a connection point where apps, messages,
-notifications, and service infrastructure meet.
+## 이름
 
-## Product Boundary
+`nexo`는 `nexus`에서 온 이름이다. 여러 앱, 메시지, 알림, 서비스 인프라가 만나는 연결 지점을 뜻한다.
 
-- `packages/messaging_flutter/` is the Nexo-owned product surface. It should
-  hold reusable messaging, push notification, native bridge, and notification
-  tap/intake behavior that multiple Flutter apps can consume.
-- Consuming apps such as IOP, NomadCode, and ALT own their product UI, workflow
-  semantics, and app-specific business logic. They should depend on Nexo for the
-  common messaging runtime instead of copying native push/messaging integration.
-- Mattermost upstream code is a comparison and validation baseline, not the main
-  customization surface. Keep `apps/mattermost`, `services/core`, and
-  `services/push-proxy` close to their recorded upstream snapshots unless an
-  explicit upstream refresh or small targeted patch is being reviewed.
-- When Mattermost product behavior does not fit a consuming app, prefer adding a
-  narrow Nexo plugin contract, wrapper, configuration point, or documented
-  integration path over changing the upstream snapshots directly.
+## 제품 경계
 
-## Current Status
+- `packages/messaging_flutter/`는 Nexo가 소유하는 제품 표면이다. 여러 Flutter 앱이 소비할 수 있는 메시징, 푸시 알림, 네이티브 브리지, 알림 탭/수신 동작을 이곳에 둔다.
+- 이 패키지를 소비하는 앱은 각자의 제품 UI, 워크플로우 의미, 앱별 비즈니스 로직을 소유한다. 공통 메시징 런타임은 Nexo에 의존하고, 앱별 동작은 각 프로젝트에 남긴다.
+- Mattermost 업스트림 코드는 비교와 검증을 위한 기준선이지 주 커스터마이징 표면이 아니다. 명시적인 업스트림 갱신이나 작은 대상 패치를 검토하는 경우가 아니라면 `apps/mattermost`, `services/core`, `services/push-proxy`는 기록된 업스트림 스냅샷에 가깝게 유지한다.
+- Mattermost 제품 동작이 소비 앱에 맞지 않을 때는 업스트림 스냅샷을 직접 크게 바꾸기보다 좁은 Nexo 플러그인 계약, 래퍼, 설정 지점, 문서화된 통합 경로를 추가한다.
 
-- `packages/messaging_flutter/` is the main product surface: an Android-first Flutter messaging and push-notification plugin package.
-- `apps/flutter-test/` is the plugin test app.
-- `apps/mattermost/` is the original Mattermost mobile app repository snapshot (see `apps/mattermost/UPSTREAM.md`).
-- `services/core/` is the Mattermost server repository clone.
-- `services/push-proxy/` is the Mattermost push-proxy repository snapshot (see `services/push-proxy/UPSTREAM.md`).
-- Public package, import, and native identifiers are being moved to Nexo-owned names.
-- iOS and macOS plugin scaffolds exist, but Android is the current implementation target.
+## 현재 상태
 
-## Quick Start
+- `packages/messaging_flutter/`는 Android 우선 Flutter 메시징/푸시 알림 플러그인 패키지이며, 이 저장소의 주 제품 표면이다.
+- `apps/flutter-test/`는 플러그인을 검증하는 테스트용 Flutter 앱이다.
+- `apps/mattermost/`는 원래 Mattermost 모바일 앱 저장소 스냅샷이다. 기준선은 `apps/mattermost/UPSTREAM.md`를 본다.
+- `services/core/`는 Mattermost 서버 저장소 clone이다.
+- `services/push-proxy/`는 Mattermost push-proxy 저장소 스냅샷이다. 기준선은 `services/push-proxy/UPSTREAM.md`를 본다.
+- 공개 package, import, 네이티브 identifier는 Nexo 소유 이름으로 전환 중이다.
+- iOS와 macOS 플러그인 scaffold는 있지만, 현재 구현 대상은 Android다.
 
-Show development entrypoints:
+## 빠른 시작
+
+개발 진입점을 확인한다.
 
 ```sh
 bin/dev
 ```
 
-Run Flutter package and `flutter-test` host checks:
+Flutter 패키지와 `flutter-test` 호스트 검증을 실행한다.
 
 ```sh
 bin/test
 bin/lint
 ```
 
-Start the core compose runtime:
+core compose 런타임을 실행한다.
 
 ```sh
 cd services/core/compose
@@ -70,87 +50,83 @@ cp .env.example .env
 docker compose up
 ```
 
-## Commands
+## 주요 명령
 
-| Purpose | Command | Notes |
+| 목적 | 명령 | 비고 |
 | --- | --- | --- |
-| Show development entrypoints | `bin/dev` | Prints test host, plugin, and core compose commands |
-| Run default tests | `bin/test` | Runs Flutter tests; skips Go tests by default |
-| Run default lint | `bin/lint` | Runs Flutter analyze; skips Go vet by default |
-| Run default build | `bin/build` | Runs configured app builds; skips `apps/flutter-test` web build when web is not configured and skips Go build by default |
-| Include server Go tests | `NEXO_CORE_GO_TEST=1 bin/test` | Requires local `go` |
-| Include server Go vet | `NEXO_CORE_GO_LINT=1 bin/lint` | Requires local `go` |
-| Include server Go build | `NEXO_CORE_GO_BUILD=1 bin/build` | Requires local `go` |
-| Run the `flutter-test` host directly | `cd apps/flutter-test && flutter run` | Requires Flutter SDK |
-| Test the plugin directly | `cd packages/messaging_flutter && flutter test` | Requires Flutter SDK |
-| Run Android native unit tests | `cd apps/flutter-test/android && ./gradlew testDebugUnitTest` | Requires Android SDK |
+| 개발 진입점 확인 | `bin/dev` | 테스트 호스트, 플러그인, core compose 명령을 출력한다. |
+| 기본 테스트 실행 | `bin/test` | Flutter 테스트를 실행하고, 기본값에서는 Go 테스트를 건너뛴다. |
+| 기본 lint 실행 | `bin/lint` | Flutter analyze를 실행하고, 기본값에서는 Go vet을 건너뛴다. |
+| 기본 build 실행 | `bin/build` | 설정된 앱 build를 실행한다. web 설정이 없으면 `apps/flutter-test` web build를 건너뛰고, 기본값에서는 Go build를 건너뛴다. |
+| 서버 Go 테스트 포함 | `NEXO_CORE_GO_TEST=1 bin/test` | 로컬 `go`가 필요하다. |
+| 서버 Go vet 포함 | `NEXO_CORE_GO_LINT=1 bin/lint` | 로컬 `go`가 필요하다. |
+| 서버 Go build 포함 | `NEXO_CORE_GO_BUILD=1 bin/build` | 로컬 `go`가 필요하다. |
+| `flutter-test` 호스트 직접 실행 | `cd apps/flutter-test && flutter run` | Flutter SDK가 필요하다. |
+| 플러그인 직접 테스트 | `cd packages/messaging_flutter && flutter test` | Flutter SDK가 필요하다. |
+| Android 네이티브 단위 테스트 실행 | `cd apps/flutter-test/android && ./gradlew testDebugUnitTest` | Android SDK가 필요하다. |
 
-The `bin/*` helpers skip checks when a required local tool is unavailable. Note
-any skipped checks in work reports.
+`bin/*` helper는 필요한 로컬 도구가 없으면 일부 검증을 건너뛸 수 있다. 작업 보고에는 건너뛴 검증을 함께 적는다.
 
-## Structure
+## 구조
 
-| Path | Role |
+| 경로 | 역할 |
 | --- | --- |
-| `packages/messaging_flutter/` | Main Flutter messaging and push-notification package |
-| `apps/flutter-test/` | `flutter-test` app for package integration checks |
-| `apps/mattermost/` | Mattermost mobile app repository snapshot |
-| `services/core/` | Mattermost server repository clone and current compose runtime |
-| `services/push-proxy/` | Mattermost push-proxy repository snapshot |
-| `docs/` | Cross-module product, migration, and operations notes |
-| `bin/` | Workspace helper entrypoints |
-| `agent-ops/` | Agent rules, domain rules, and common skill entrypoints |
+| `packages/messaging_flutter/` | 주 Flutter 메시징/푸시 알림 패키지 |
+| `apps/flutter-test/` | 패키지 통합 검증용 `flutter-test` 앱 |
+| `apps/mattermost/` | Mattermost 모바일 앱 저장소 스냅샷 |
+| `services/core/` | Mattermost 서버 저장소 clone과 현재 compose 런타임 |
+| `services/push-proxy/` | Mattermost push-proxy 저장소 스냅샷 |
+| `docs/` | 모듈 간 제품, migration, 운영 문서 |
+| `bin/` | workspace helper 진입점 |
+| `agent-ops/` | agent 규칙, domain rule, 공통 skill 진입점 |
 
-## Work Context
+## 작업 맥락
 
-- Start by reading `AGENTS.md`, then `agent-ops/rules/project/rules.md`.
-- Follow path-specific domain rules under `agent-ops/rules/project/domain/*/rules.md`.
-- For standard tasks such as README, plan, review, or commit/push, route through `agent-ops/skills/common/router.md`.
-- Treat `packages/messaging_flutter/` as the primary product. App-specific product UI and business logic belong in consuming apps outside this repository.
-- Treat IOP, NomadCode, and ALT as expected sibling consumers of the Nexo messaging layer; keep shared behavior in the plugin and app-specific behavior in those projects.
-- Treat `apps/flutter-test/` only as the plugin integration test host; do not grow it into a product app or duplicate plugin internals there.
-- Treat `apps/mattermost`, `services/core`, and `services/push-proxy` as original Mattermost repository clones, not as nexo-owned app or server products.
-- Do not change `services/core/UPSTREAM.md` baseline information without an explicit upstream decision.
-- Keep upstream working clones outside this repository under a sibling/external `mattermost/` staging folder, one clone for each original repository.
-- Track each upstream repository on its recorded staging branch: `main` for `mattermost-mobile`, and `master` for `mattermost` and `mattermost-push-proxy`. When a tracked branch changes or a refresh is intentionally scheduled, take a fresh snapshot from staging and open a merge request into this repository.
-- Record the exact upstream commit SHA for every snapshot that enters this repository.
-- Prefer one merge request per upstream repository snapshot: `apps/mattermost`, `services/core`, or `services/push-proxy`.
-- Never auto-apply staging updates into this repository; review the snapshot diff and run the relevant smoke checks first.
-- Keep nexo-specific patches outside the upstream snapshot where possible, using compose, docs, wrappers, or small explicit patches.
+- 작업을 시작할 때는 `AGENTS.md`를 읽고, 이어서 `agent-ops/rules/project/rules.md`를 읽는다.
+- 변경 경로에 맞는 domain rule은 `agent-ops/rules/project/domain/*/rules.md`에서 확인한다.
+- README, plan, review, commit/push 같은 표준 작업은 `agent-ops/skills/common/router.md`를 통해 공통 skill로 라우팅한다.
+- `packages/messaging_flutter/`를 주 제품으로 본다. 앱별 제품 UI와 비즈니스 로직은 이 저장소가 아니라 패키지를 소비하는 앱의 책임이다.
+- 여러 sibling 또는 외부 제품이 Nexo 메시징 계층을 소비할 수 있다. 공통 동작은 플러그인에 두고, 앱별 동작은 각 프로젝트에 둔다.
+- `apps/flutter-test/`는 플러그인 통합 검증용 호스트로만 본다. 제품 앱으로 키우거나 플러그인 내부 동작을 복제하지 않는다.
+- `apps/mattermost`, `services/core`, `services/push-proxy`는 Mattermost 원본 저장소 clone으로 본다. nexo 소유 앱이나 독자 서버 제품으로 재정의하지 않는다.
+- 명시적인 업스트림 결정 없이 `services/core/UPSTREAM.md`의 기준선 정보를 바꾸지 않는다.
+- 업스트림 작업 clone은 이 저장소 밖의 sibling/external `mattermost/` staging 폴더에 원본 저장소별로 둔다.
+- 업스트림 저장소는 기록된 branch를 따라간다. `mattermost-mobile`은 `main`, `mattermost`와 `mattermost-push-proxy`는 `master`를 기준으로 하며, branch 변경 시점이나 의도적으로 정한 갱신 시점에 스냅샷을 떠서 이 저장소로 merge 요청한다.
+- 이 저장소에 들어오는 스냅샷은 원본 저장소별 정확한 commit SHA를 기록한다.
+- merge 요청은 원칙적으로 업스트림 저장소별로 분리한다. `apps/mattermost`, `services/core`, `services/push-proxy` 스냅샷을 한 요청에 섞지 않는다.
+- staging pull 결과를 이 저장소에 자동 반영하지 않는다. 스냅샷 diff와 관련 smoke 검증을 확인한 뒤 merge 요청한다.
+- Nexo 전용 패치는 가능한 한 업스트림 스냅샷 밖의 compose, 문서, 래퍼, 작고 명시적인 패치로 둔다.
 
-## Development Flow
+## 개발 흐름
 
-1. Read the domain rule for the path you will change.
-2. Make focused changes inside the owning module.
-3. Run the smallest useful verification for the change.
-4. Use `bin/test`, `bin/lint`, or `bin/build` when workspace-level checks are needed.
-5. Use `services/core/compose/` when runtime server verification is needed.
+1. 변경할 경로의 domain rule을 읽는다.
+2. 소유 모듈 안에서 변경 범위를 좁게 유지한다.
+3. 변경에 맞는 가장 작은 유효 검증을 실행한다.
+4. workspace 수준 검증이 필요하면 `bin/test`, `bin/lint`, `bin/build`를 사용한다.
+5. 서버 런타임 검증이 필요하면 `services/core/compose/`를 사용한다.
 
-## Environment Variables
+## 환경 변수
 
 ### Core Compose
 
-| Name | Description | Required |
+| 이름 | 설명 | 필수 |
 | --- | --- | --- |
-| `NEXO_DB_PASSWORD` | Password for the Postgres `mmuser` account | Yes |
-| `NEXO_SITE_URL` | Site URL used by the core service | Yes |
-| `NEXO_CORE_PORT` | Host port mapped to core `8065` | No |
-| `NEXO_PUSH_PROXY_PORT` | Host port mapped to push-proxy `8066` | No |
+| `NEXO_DB_PASSWORD` | Postgres `mmuser` 계정 password | 예 |
+| `NEXO_SITE_URL` | core service가 사용하는 site URL | 예 |
+| `NEXO_CORE_PORT` | core `8065`에 매핑할 host port | 아니오 |
+| `NEXO_PUSH_PROXY_PORT` | push-proxy `8066`에 매핑할 host port | 아니오 |
 
-See `services/core/compose/.env.example` for example values. Do not commit real
-`.env` files or runtime data. The Docker network subnet is fixed to
-`172.38.0.0/16`; reserve this range for nexo and do not reuse it for other Docker
-networks.
+예시는 `services/core/compose/.env.example`를 본다. 실제 `.env` 파일이나 런타임 데이터는 커밋하지 않는다. Docker network subnet은 `172.38.0.0/16`으로 고정되어 있으므로, 이 범위는 nexo용으로 예약하고 다른 Docker network에서 재사용하지 않는다.
 
-### Optional Verification
+### 선택 검증
 
-| Name | Description | Default |
+| 이름 | 설명 | 기본값 |
 | --- | --- | --- |
-| `NEXO_CORE_GO_TEST` | Run server Go tests from `bin/test` | `0` |
-| `NEXO_CORE_GO_LINT` | Run server Go vet from `bin/lint` | `0` |
-| `NEXO_CORE_GO_BUILD` | Run server Go build from `bin/build` | `0` |
+| `NEXO_CORE_GO_TEST` | `bin/test`에서 서버 Go 테스트를 실행한다. | `0` |
+| `NEXO_CORE_GO_LINT` | `bin/lint`에서 서버 Go vet을 실행한다. | `0` |
+| `NEXO_CORE_GO_BUILD` | `bin/build`에서 서버 Go build를 실행한다. | `0` |
 
-## Reference Documents
+## 참고 문서
 
 - `AGENTS.md`
 - `agent-ops/rules/project/rules.md`