memi-board 0.52.0 → 0.52.2

package/docs/firebase-setup.md

@@ -1,37 +1,37 @@
-# Firebase 프로젝트 준비 (처음 설치하는 경우)
+# Firebase project setup (first-time install)
 
-이 모듈을 처음 붙이는 프로젝트, 특히 Firebase를 아직 안 써본 프로젝트라면 README의 "설치" 섹션만으로는 부족하다. 여기 순서대로 하면 된다.
+If this is the first time you are adding this module to a project, especially one that has never used Firebase, the README's "Installation" section is not enough. Follow the steps below in order.
 
-[호스트 설치 가이드](host-integration.md) · [국제화·번역 설정](internationalization.md) · [역할 마이그레이션](roles-migration.md)
+[Host installation guide](host-integration.md) · [Internationalization and translation](internationalization.md) · [Role migration](roles-migration.md)
 
-## 1. 사전 준비
+## 1. Prerequisites
 
-- Node.js + pnpm (또는 npm/yarn)
-- Nuxt **4.0 이상**, `@nuxt/ui` **4.0 이상**
-- Firebase CLI: `npm i -g firebase-tools` 후 `firebase login`
+- Node.js + pnpm (or npm/yarn)
+- Nuxt **4.0 or later**, `@nuxt/ui` **4.0 or later**
+- Firebase CLI: `npm i -g firebase-tools`, then `firebase login`
 
-## 2. Firebase 프로젝트 만들기 (아직 없다면)
+## 2. Create a Firebase project (if you don't have one)
 
-1. [Firebase 콘솔](https://console.firebase.google.com)에서 새 프로젝트를 만든다.
-2. **Firestore Database**를 사용 설정한다 (Native mode).
-3. **Storage**를 사용 설정한다.
-4. **Authentication**을 사용 설정하고, Sign-in method에서 쓸 provider(Google/Apple/이메일-비밀번호)를 켠다.
+1. Create a new project in the [Firebase console](https://console.firebase.google.com).
+2. Enable **Firestore Database** (Native mode).
+3. Enable **Storage**.
+4. Enable **Authentication**, and turn on the providers you need (Google/Apple/Email/Password) under Sign-in method.
 
-이미 있는 Firebase 프로젝트에 붙이는 거라면 이 단계는 건너뛰고, 위 세 서비스가 켜져 있는지만 확인한다.
+If you are adding the board to an existing Firebase project, skip this step and just confirm that the three services above are enabled.
 
-## 3. `firebaseConfig` 값 가져오기
+## 3. Get the `firebaseConfig` values
 
-Firebase 콘솔 → 프로젝트 설정(톱니바퀴) → **일반** 탭 → "내 앱" 섹션 → 웹 앱이 없으면 추가 → "SDK 설정 및 구성"에서 `apiKey`/`authDomain`/`projectId`/`storageBucket`/`messagingSenderId`/`appId` 값을 그대로 복사해 `nuxt.config.ts`의 `vuefire.config`에 붙여넣는다(memi-board가 아니라 호스트의 nuxt-vuefire 설정이다 — README [설치](../README.md#설치) 참고).
+Firebase console → Project settings (gear icon) → **General** tab → "Your apps" section → add a web app if there is none → under "SDK setup and configuration", copy the `apiKey`/`authDomain`/`projectId`/`storageBucket`/`messagingSenderId`/`appId` values as-is into `vuefire.config` in `nuxt.config.ts` (this is the host app's nuxt-vuefire config, not memi-board's — see README [Installation](../README.md#installation)).
 
-## 4. 호스트 프로젝트를 Firebase CLI에 연결
+## 4. Connect the host project to the Firebase CLI
 
-프로젝트 루트에 아직 `firebase.json`/`.firebaserc`가 없다면:
+If the project root does not have `firebase.json`/`.firebaserc` yet:
 
 ```bash
 firebase init firestore storage
 ```
 
-또는 수동으로 만든다:
+Or create them manually:
 
 ```json
 // .firebaserc
@@ -43,22 +43,22 @@ firebase init firestore storage
 {
   "firestore": { "rules": "firestore.rules", "indexes": "firestore.indexes.json" },
   "storage": {
-    "bucket": "<vuefire.config.storageBucket 과 동일한 값>",
+    "bucket": "<same value as vuefire.config.storageBucket>",
     "rules": "storage.rules"
   }
 }
 ```
 
-`storage.bucket`은 호스트 `vuefire.config.storageBucket`과 **같아야** 한다. 예: `my-app.appspot.com`.
+`storage.bucket` **must match** the host's `vuefire.config.storageBucket`. Example: `my-app.appspot.com`.
 
-이미 Firebase CLI를 쓰고 있는 프로젝트라면, `firebase.json`에 `firestore.rules`/`storage.rules` 경로가 있는지만 보지 말고 **버킷 이름**도 확인한다.
+If the project already uses the Firebase CLI, don't just check that `firebase.json` has the `firestore.rules`/`storage.rules` paths — check the **bucket name** too.
 
-구 프로젝트는 버킷이 두 개일 수 있다.
+Older projects may have two buckets:
 
-- `*.appspot.com` — 예전 웹 앱 SDK snippet 의 `storageBucket`
-- `*.firebasestorage.app` — 콘솔/CLI 기본 버킷
+- `*.appspot.com` — the `storageBucket` from the older web app SDK snippet
+- `*.firebasestorage.app` — the console/CLI default bucket
 
-`firebase deploy --only storage`에 `bucket`이 없으면 **기본 버킷**에만 규칙이 올라간다. 앱은 `appspot.com`에 올리는데 규칙은 `firebasestorage.app`에만 있으면, 에디터 이미지에서 `storage/unauthorized`가 난다. 둘 다 쓰면 배열로 같은 규칙을 올린다.
+If `firebase deploy --only storage` has no `bucket`, the rules are deployed only to the **default bucket**. If the app uploads to `appspot.com` but the rules exist only on `firebasestorage.app`, editor images fail with `storage/unauthorized`. If you use both, deploy the same rules as an array:
 
 ```json
 "storage": [
@@ -67,111 +67,111 @@ firebase init firestore storage
 ]
 ```
 
-글 삭제가 `storage/unauthorized` (`access 'memiBoardPosts/{postId}'`) 로 실패하면 버킷이 아니라 **list 경로**다. `listAll` 접두사는 `memiBoardPosts/{postId}/` 이라 `match /memiBoardPosts/{postId} { allow list }` 만으로는 안 된다. `docs/storage.rules.example`의 `{postId}/{allPaths=**}` 블록을 그대로 넣고 `firebase deploy --only storage` 한다.
+If deleting a post fails with `storage/unauthorized` (`access 'memiBoardPosts/{postId}'`), the problem is the **list path**, not the bucket. The `listAll` prefix is `memiBoardPosts/{postId}/`, so `match /memiBoardPosts/{postId} { allow list }` alone is not enough. Copy the `{postId}/{allPaths=**}` block from `docs/storage.rules.example` as-is and run `firebase deploy --only storage`.
 
-## 5. 게시판 Security Rules 병합 + 배포
+## 5. Merge and deploy the board Security Rules
 
-README의 [Security Model](../README.md#security-model) 섹션대로 `docs/firestore.rules.example`/`docs/storage.rules.example`을 프로젝트 규칙 파일에 병합한 뒤:
+Merge `docs/firestore.rules.example`/`docs/storage.rules.example` into the project's rules files as described in the README's [Security Model](../README.md#security-model) section, then:
 
 ```bash
 firebase deploy --only firestore:rules,storage
 ```
 
-**병합만 하고 배포를 안 하면 글쓰기·댓글에서 `permission-denied`가 난다** — 가장 흔한 설치 실수다.
+**If you merge but don't deploy, writing posts and comments fails with `permission-denied`** — this is the most common installation mistake.
 
-### 0.45.1 규칙 변경과 기존 호스트 전환
+### 0.45.1 rule changes and migrating existing hosts
 
-0.46 이상에서는 아래 파일 관리의 전역 역할이 **admin/owner**다. staff/manager는 담당 콘텐츠를 관리하지만 타인 파일의 수정·삭제는 기본 규칙으로 허용하지 않는다. 신규 설치의 최초 역할은 `owner`로 지정하고, 기존 admin·staff 계정은 [역할 마이그레이션](roles-migration.md) 절차로 이전한다.
+From 0.46 onward, the global roles for the file management described below are **admin/owner**. staff/manager manage their assigned content, but the default rules do not let them modify or delete other users' files. For a new install, set the first role to `owner`; migrate existing admin and staff accounts using the [role migration](roles-migration.md) procedure.
 
 
-0.45.1은 클라이언트와 Firestore·Storage 규칙을 함께 갱신해야 한다. 사이트 자동 배포는 Firebase 규칙 배포를 대신하지 않는다.
+0.45.1 requires updating the client and the Firestore and Storage rules together. Automatic site deployment does not replace deploying the Firebase rules.
 
-| 대상 | 변경 내용 |
+| Target | Change |
 |------|-----------|
-| 글 수정 | `boardId`·`authorUid` 변경을 금지하고 `listed` 변경을 공개 범위 전환으로 제한한다. |
-| 글·본문 동시 생성 | 본문 쓰기에서 `getAfter()`로 batch 적용 후 부모 글의 소유권을 확인한다. |
-| 공개 범위 전환 | 보드 설정의 `visibilityTransition` 동안 새 글·댓글 생성과 일반 글 수정을 잠근다. 담당 관리자의 `listed` 동기화는 허용한다. |
-| 삭제·감사 기록 | 콘텐츠 작성자·담당 관리자가 연관 좋아요를 정리할 수 있다. 글을 지워도 신고 기록은 남긴다. |
-| 이미지·첨부 업로드 | 기존 글은 작성자 또는 전역 admin·owner만 쓴다. 글 저장 전에는 업로드 파일의 `customMetadata.ownerUid`가 로그인 UID와 같아야 한다. 덮어쓰기는 기존 파일의 `ownerUid`도 확인한다. |
-| 파일 삭제 | 글 문서가 있으면 작성자 또는 전역 admin·owner, 없으면 파일에 기록된 `ownerUid` 본인만 삭제한다. |
+| Post updates | Changing `boardId` or `authorUid` is forbidden, and changing `listed` is limited to visibility transitions. |
+| Creating a post and its body together | The body write uses `getAfter()` to check ownership of the parent post after the batch is applied. |
+| Visibility transitions | While the board settings have `visibilityTransition`, creating new posts and comments and regular post edits are locked. Assigned managers may still sync `listed`. |
+| Deletion and audit records | Content authors and assigned managers can clean up related likes. Report records remain even when the post is deleted. |
+| Image and attachment uploads | For existing posts, only the author or a global admin/owner can write. Before the post is saved, the uploaded file's `customMetadata.ownerUid` must equal the signed-in UID. Overwrites also check the existing file's `ownerUid`. |
+| File deletion | If the post document exists, only the author or a global admin/owner can delete; otherwise only the user recorded in the file's `ownerUid`. |
 
-적용 순서:
+Rollout order:
 
-1. 호스트에서 `memi-board@^0.45.1` 이상을 설치하고 lockfile을 갱신한다. 직접 만든 업로드 코드도 이미지·썸네일·첨부파일 모두에 `customMetadata: { ownerUid: user.uid }`를 넣는다.
-2. 현재 설치한 버전 예제의 함수와 컬렉션·경로별 규칙 전체를 호스트에 병합한다. 컬렉션 이름을 바꿨다면 함수 내부 Firestore 경로도 맞춘다. 예전의 `!postExists(postId)`만으로 파일 쓰기·삭제를 허용하는 조건은 제거한다. Rules의 겹치는 `match` 중 하나라도 허용하면 접근이 가능하므로, 넓은 `allow write`를 남겨두지 않는다.
-3. 에뮬레이터에서 두 계정으로 새 글·본문 동시 저장, 이미지·첨부 업로드, 타인 파일 덮어쓰기·삭제 거절, 댓글 좋아요 정리, 숨김 전환 재시도를 확인한다.
-4. 새 클라이언트와 규칙 배포를 같은 배포 작업으로 진행하고 앱이 사용하는 모든 버킷에 적용한다. 새 규칙이 적용되면 기존 브라우저의 구버전 클라이언트는 저장 전 업로드에 `ownerUid`가 없어 거절될 수 있으므로 새 버전을 불러온 뒤 재시도한다. 아래 교차 서비스 IAM 설정도 확인한다.
+1. In the host app, install `memi-board@^0.45.1` or later and update the lockfile. Any custom upload code must also set `customMetadata: { ownerUid: user.uid }` on images, thumbnails, and attachments.
+2. Merge all functions and per-collection/per-path rules from the example of the version you installed into the host. If you renamed collections, update the Firestore paths inside the functions too. Remove old conditions that allow file writes or deletes based only on `!postExists(postId)`. Access is granted if any overlapping `match` in the rules allows it, so don't leave a broad `allow write` in place.
+3. In the emulator, with two accounts, verify: saving a new post and body together, image and attachment uploads, rejection of overwriting or deleting another user's files, comment like cleanup, and retrying a hide transition.
+4. Deploy the new client and the rules in the same deployment, and apply them to every bucket the app uses. Once the new rules are live, old clients in existing browsers may be rejected because their pre-save uploads lack `ownerUid`; reload the new version and retry. Also check the cross-service IAM setup below.
 
-기존 글의 파일은 `ownerUid`가 없어도 부모 글의 작성자·역할로 판단하므로 메타데이터 일괄 수정이 필요하지 않다. 반면 부모 글 문서가 없고 `ownerUid`도 없는 예전 고아 파일은 클라이언트에서 수정·삭제할 수 없다. 필요한 정리는 신뢰할 수 있는 Admin SDK 또는 콘솔에서 수행한다.
+Files on existing posts are authorized by the parent post's author and roles even without `ownerUid`, so no bulk metadata update is needed. However, old orphaned files that have neither a parent post document nor an `ownerUid` cannot be modified or deleted from the client. Do any necessary cleanup from a trusted Admin SDK or the console.
 
-공개 범위 전환 중 실패하면 `visibilityTransition`을 임의로 지우거나 반대 범위로 바꾸지 말고, 설정 화면에서 **같은 목표 범위로 다시 저장**해 동기화를 완료한다. 숨김 전환은 콘텐츠의 `listed`를 먼저 내리고 마지막에 `visibility: 'hidden'`을 확정한다. 공개 복귀는 보드 공개를 먼저 허용한 뒤 콘텐츠를 동기화하고 전환 표시를 비운다.
+If a visibility transition fails, don't manually clear `visibilityTransition` or switch it to the opposite visibility; instead, **save again with the same target visibility** in the settings screen to complete the sync. A hide transition first lowers the content's `listed`, then finalizes `visibility: 'hidden'` last. Returning to public first allows the board to be public, then syncs the content, then clears the transition marker.
 
-Storage의 Firestore 조회 제한은 서로 다른 문서 최대 2개이므로 예제는 글 문서와 사용자 역할 문서만 읽는다. 따라서 Storage의 admin·owner는 보드 담당 여부와 무관한 전역 파일 관리 권한을 유지한다. Firestore의 담당 스태프 범위와 혼동하지 않는다. [공식 조회 제한](https://firebase.google.com/docs/storage/security/rules-conditions#enhance_with_firestore)을 참고한다.
+Storage rules can read at most 2 distinct Firestore documents, so the example reads only the post document and the user role document. As a result, admin/owner in Storage keep global file management rights regardless of board assignment. Don't confuse this with the assigned-staff scope in Firestore. See the [official access limits](https://firebase.google.com/docs/storage/security/rules-conditions#enhance_with_firestore).
 
-예제의 파일 읽기와 목록 조회는 계속 공개다. 숨김 보드·비공개 초안 파일까지 비공개로 저장해야 하는 서비스는 별도의 Storage 읽기 정책을 설계해야 한다.
+File reads and listing in the example remain public. Services that need files of hidden boards or private drafts to be stored privately must design a separate Storage read policy.
 
-### Storage 규칙의 Firestore 조회 권한 (부모/호스트 프로젝트 필수 설정)
+### Firestore read access for Storage rules (required host app setup)
 
-Storage 예시 규칙은 이미지·첨부 업로드와 파일 삭제 시 `firestore.exists()` / `firestore.get()`으로 글의 존재 여부, `authorUid`, 사용자 `role`을 조회한다. 따라서 **호스트 Firebase 프로젝트의 Storage 서비스 계정**에 Firestore 조회 역할이 필요하다. 패키지 설치나 Firestore Rules 배포만으로 이 IAM 설정이 완료되지는 않는다.
+On image/attachment uploads and file deletion, the example Storage rules use `firestore.exists()` / `firestore.get()` to look up whether the post exists, its `authorUid`, and the user's `role`. The **Storage service account of the host app's Firebase project** therefore needs a Firestore read role. Installing the package or deploying the Firestore rules does not complete this IAM setup.
 
-호스트 프로젝트 관리자가 다음을 설정한다:
+An administrator of the host project sets this up as follows:
 
-1. 호스트 저장소에서 위 배포 명령을 대화형으로 실행한다. Firebase CLI가 교차 서비스 규칙용 IAM 역할 추가를 물으면 승인한다. Firebase 콘솔에서 Storage Rules를 저장할 때 표시되는 연결 권한 안내로도 설정할 수 있다.
-2. Google Cloud Console → **IAM 및 관리자 → IAM**에서 같은 Firebase 프로젝트를 선택하고 **Google 제공 역할 부여 포함(Include Google-provided role grants)**을 켠다.
-3. `service-<PROJECT_NUMBER>@gcp-sa-firebasestorage.iam.gserviceaccount.com` 계정을 찾아 **Firebase Rules Firestore Service Agent** (`roles/firebaserules.firestoreServiceAgent`) 역할이 있는지 확인한다. `<PROJECT_NUMBER>`는 프로젝트 ID가 아니라 Firebase 프로젝트 설정의 숫자 프로젝트 번호다. 역할이 없으면 IAM 변경 권한이 있는 호스트 관리자가 이 서비스 계정에 추가한다.
-4. 권한 반영 후 로그인 상태에서 새 글에 20MiB 미만의 작은 첨부파일을 올려 확인한다. 기존 글에서는 작성자·스태프의 첨부 작업도 확인한다.
+1. Run the deploy command above interactively from the host repository. When the Firebase CLI asks whether to add the IAM role for cross-service rules, approve it. You can also grant it from the connection permission prompt shown when saving Storage Rules in the Firebase console.
+2. In the Google Cloud Console → **IAM & Admin → IAM**, select the same Firebase project and turn on **Include Google-provided role grants**.
+3. Find the `service-<PROJECT_NUMBER>@gcp-sa-firebasestorage.iam.gserviceaccount.com` account and confirm it has the **Firebase Rules Firestore Service Agent** (`roles/firebaserules.firestoreServiceAgent`) role. `<PROJECT_NUMBER>` is the numeric project number from the Firebase Project settings, not the project ID. If the role is missing, a host administrator with permission to change IAM adds it to this service account.
+4. After the permission takes effect, verify by uploading a small attachment (under 20 MiB) to a new post while signed in. On existing posts, also verify attachment operations by the author and staff.
 
-이 역할은 프로젝트의 Firestore 문서 조회(`datastore.entities.get`)를 허용한다. 일반 사용자 계정에 부여하는 역할이 아니며, Firestore 쓰기·삭제 권한은 포함하지 않는다. Storage 규칙의 소유권·역할 검사는 그대로 유지한다.
+This role allows reading Firestore documents in the project (`datastore.entities.get`). It is not a role for regular user accounts, and it does not include Firestore write or delete permissions. The ownership and role checks in the Storage rules remain in place.
 
-**CI의 `--non-interactive` 배포 성공만으로 IAM 설정까지 완료됐다고 판단하지 않는다.** 최초 설정은 호스트 관리자가 대화형 배포 또는 IAM 콘솔에서 수행하고, 위 서비스 계정의 역할을 확인한다.
+**Do not assume IAM setup is complete just because a `--non-interactive` deploy in CI succeeded.** The host administrator must do the initial setup via an interactive deploy or the IAM console, and confirm the role on the service account above.
 
-2MB ZIP처럼 용량 조건을 충족해도 이 권한이 없으면 `memiBoardPosts/{postId}/attachments/...`에서 `storage/unauthorized`가 날 수 있다. 새 글 문서가 아직 없어도 `firestore.exists()` 조회 자체에는 권한이 필요하다. 0.45.1의 본문 이미지 업로드도 같은 Firestore 조회 권한이 필요하다.
+Even when the size limit is met, as with a 2 MB ZIP, uploads to `memiBoardPosts/{postId}/attachments/...` can fail with `storage/unauthorized` without this permission. Even if the new post document doesn't exist yet, the `firestore.exists()` lookup itself requires the permission. Body image uploads in 0.45.1 need the same Firestore read permission.
 
-공식 근거: [교차 서비스 Storage Rules 권한 설정](https://firebase.google.com/docs/rules/manage-deploy#manage_permissions_for_cross-service_cloud_storage_security_rules), [역할의 포함 권한](https://docs.cloud.google.com/iam/docs/roles-permissions/firebaserules#firebaserules.firestoreServiceAgent).
+Official references: [Managing permissions for cross-service Storage Rules](https://firebase.google.com/docs/rules/manage-deploy#manage_permissions_for_cross-service_cloud_storage_security_rules), [Permissions included in the role](https://docs.cloud.google.com/iam/docs/roles-permissions/firebaserules#firebaserules.firestoreServiceAgent).
 
-## 6. 로그인 공급자 설정
+## 6. Sign-in provider setup
 
 ### Google
 
-Firebase 콘솔 → Authentication → Sign-in method에서 Google을 활성화하기만 하면 된다. 추가 설정 없음.
+Just enable Google in Firebase console → Authentication → Sign-in method. No further setup.
 
 ### Apple
 
-Google보다 손이 더 간다:
+This takes more work than Google:
 
-1. Firebase 콘솔에서 Apple 로그인을 활성화한다.
-2. [Apple Developer](https://developer.apple.com/account) 계정에서 **Services ID**를 새로 만든다.
-3. 그 Services ID의 "Web Authentication Configuration"에 콜백 도메인을 등록한다 — Domains에 `{authDomain}`(Firebase 프로젝트의 authDomain, 보통 `<project-id>.firebaseapp.com`), Return URL에 `https://{authDomain}/__/auth/handler`.
-4. Apple Developer의 **Keys**에서 "Sign in with Apple" 키를 새로 만든다 (기존에 다른 용도 키가 있어도 별도로 새로 만들어야 한다).
-5. Team ID, 방금 만든 키의 Key ID, 그 키의 개인 키(`.p8` 파일 내용)를 Firebase 콘솔의 Apple 로그인 설정 화면에 입력한다.
+1. Enable Apple sign-in in the Firebase console.
+2. Create a new **Services ID** in your [Apple Developer](https://developer.apple.com/account) account.
+3. Register the callback domain in that Services ID's "Web Authentication Configuration" — under Domains, `{authDomain}` (the Firebase project's authDomain, usually `<project-id>.firebaseapp.com`); under Return URL, `https://{authDomain}/__/auth/handler`.
+4. Create a new "Sign in with Apple" key under **Keys** in Apple Developer (even if you already have keys for other purposes, you must create a separate new one).
+5. Enter the Team ID, the Key ID of the key you just created, and its private key (the contents of the `.p8` file) in the Apple sign-in settings in the Firebase console.
 
-자세한 건 [Firebase 공식 가이드](https://firebase.google.com/docs/auth/web/apple)를 따른다. 이 설정 없이 Apple 로그인 버튼을 누르면 에러가 난다.
+For details, follow the [official Firebase guide](https://firebase.google.com/docs/auth/web/apple). Without this setup, clicking the Apple sign-in button results in an error.
 
-## 7. Firebase AI Logic(Gemini) 활성화 — AI 검열용
+## 7. Enable Firebase AI Logic (Gemini) for AI moderation
 
-1. Firebase 콘솔 → **AI Logic** 에서 활성화하고, **Gemini Developer API** 를 사용하도록 설정한다.
-2. **요금제**: Spark에서도 되는 경우가 있으나 제한·쿼터가 있을 수 있다. 부족하면 Blaze.
-3. 모델: 호스트 `nuxt.config.ts`의 `memiBoard.moderation.model`에 `gemini-3.5-flash-lite` 권장.
-   `gemini-2.5-flash` 는 **신규 프로젝트에서 "no longer available to new users"** 로 404 날 수 있다.
-4. `moderation.enabled` 기본이 `true` 이므로 활성화 후 글쓰기 시 자동 호출된다. 끄려면 `enabled: false`.
+1. Enable it in Firebase console → **AI Logic**, and configure it to use the **Gemini Developer API**.
+2. **Pricing plan**: it may work on Spark, but there may be limits and quotas. If they are insufficient, use Blaze.
+3. Model: `gemini-3.5-flash-lite` is recommended for `memiBoard.moderation.model` in the host's `nuxt.config.ts`.
+   `gemini-2.5-flash` may return a 404 with **"no longer available to new users" on new projects**.
+4. `moderation.enabled` defaults to `true`, so once enabled it is called automatically when posts are written. To turn it off, set `enabled: false`.
 
-## 8. App Check 설정 (AI Logic Enforce 시 사실상 필수)
+## 8. App Check setup (effectively required when AI Logic is enforced)
 
-AI Logic / `firebaseml` 이 **Enforce** 이면 App Check 토큰 없이 검열 API가 실패한다. memi-board는 App Check를 초기화하지 않는다. **호스트 책임**이다. 기본값은 한 번만 쓰는 토큰(`useLimitedUseAppCheckTokens: true`)이라 reCAPTCHA v3 공급자로는 맞지 않는다. 플러그인 예시는 [README App Check 절](../README.md#app-check-ai-enforce-시-사실상-필수)을 따른다.
+If AI Logic / `firebaseml` is set to **Enforce**, the moderation API fails without an App Check token. memi-board does not initialize App Check. **That is the host app's responsibility.** The default uses limited-use tokens (`useLimitedUseAppCheckTokens: true`), which don't fit the reCAPTCHA v3 provider. For a plugin example, follow the [README App Check section](../README.md#app-check-effectively-required-with-ai-enforce).
 
-1. reCAPTCHA Enterprise **점수형** 웹 키를 만들고, Firebase 콘솔 App Check의 웹 앱에 그 사이트 키를 등록한다. 등록하는 웹 앱의 **appId** 가 호스트 `vuefire.config.appId` 와 같아야 한다. 시크릿 키는 클라이언트에 넣지 않는다.
-2. 브라우저 API 키 제한에 **Firebase App Check API** 를 포함한다. 이미 허용한 API는 유지한다.
-3. SPA는 `app:mounted` 이후에 `enterprise.execute` 로 토큰을 만들어 `exchangeRecaptchaEnterpriseToken` 에 `limited_use: true` 로 교환한다. `ReCaptchaEnterpriseProvider` 는 마운트 전 빈 `document.body` 에 숨은 위젯을 그리다 `appCheck/recaptcha-error` 가 난다.
-4. **로컬:** `self.FIREBASE_APPCHECK_DEBUG_TOKEN = true`(콘솔에 UUID 출력 후 App Check → 디버그 토큰 등록) 또는 등록된 고정 UUID.
-5. **프로덕션:** 디버그 토큰 사용 금지. reCAPTCHA 도메인에 실제 호스트 도메인 등록.
-6. 적용은 **AI Logic만** 켠다. Cloud Storage와 Cloud Firestore는 모니터링으로 둔다. 한 번용 토큰은 AI Logic만 받는다. Storage나 Firestore에 적용하면 이미지 업로드와 글 쓰기가 거절된다.
+1. Create a reCAPTCHA Enterprise **score-based** web key and register that site key for the web app in App Check in the Firebase console. The **appId** of the registered web app must match the host's `vuefire.config.appId`. Never put the secret key in the client.
+2. Include the **Firebase App Check API** in the browser API key restrictions. Keep the APIs that are already allowed.
+3. In an SPA, after `app:mounted`, create a token with `enterprise.execute` and exchange it via `exchangeRecaptchaEnterpriseToken` with `limited_use: true`. `ReCaptchaEnterpriseProvider` renders a hidden widget into an empty `document.body` before mounting and fails with `appCheck/recaptcha-error`.
+4. **Local:** `self.FIREBASE_APPCHECK_DEBUG_TOKEN = true` (prints a UUID to the console; register it under App Check → debug tokens) or a registered fixed UUID.
+5. **Production:** never use debug tokens. Register the real host domain in the reCAPTCHA domains.
+6. Enforce **only AI Logic**. Leave Cloud Storage and Cloud Firestore on monitoring. Only AI Logic accepts limited-use tokens. If you enforce Storage or Firestore, image uploads and post writes are rejected.
 
-## 9. Firestore 복합 인덱스
+## 9. Firestore composite indexes
 
-`memiBoardPosts`/`memiBoardComments`/`memiBoardLikes` 는 모두 최상위 flat 컬렉션이고, 보드/글 단위 스코핑은 `boardId`/`postId` 필드에 대한 `where` 동등 필터로 한다. [docs/firestore.indexes.json.example](firestore.indexes.json.example) 를 호스트 `firestore.indexes.json` 에 병합 후:
+`memiBoardPosts`/`memiBoardComments`/`memiBoardLikes` are all top-level flat collections, and board/post scoping is done with `where` equality filters on the `boardId`/`postId` fields. Merge [docs/firestore.indexes.json.example](firestore.indexes.json.example) into the host's `firestore.indexes.json`, then:
 
 ```bash
 firebase deploy --only firestore:indexes
 ```
 
-콘솔 에러에 인덱스 생성 링크가 뜨면 그걸 따라도 된다 — 위 예시 파일은 패키지가 실제로 실행하는 쿼리 기준으로 미리 정리해 둔 것이다. 컬렉션 이름을 커스터마이즈했다면(`memiBoard.postsCollection` 등) `collectionGroup` 값도 맞춰 바꾼다.
+If a console error shows an index creation link, you can follow it too — the example file above is prepared in advance based on the queries the package actually runs. If you customized collection names (`memiBoard.postsCollection`, etc.), update the `collectionGroup` values to match.

package/docs/firestore.rules.example

@@ -1,17 +1,17 @@
 // memi-board 0.23+ Firestore Rules (flat schema)
 //
 // memiBoardUsers/{uid}
-// memiBoardSettings/{boardId}          (구 memiBoards/{id} stub + settings/config 통합)
-// memiBoardPosts/{postId}(+ body/main)  boardId 필드로 보드 스코핑
-// memiBoardComments/{commentId}         postId + boardId 필드로 스코핑
-// memiBoardLikes/{likeId}               문서ID = `${postId}_${uid}` 또는 `${commentId}_${uid}`
+// memiBoardSettings/{boardId}          (merges the old memiBoards/{id} stub + settings/config)
+// memiBoardPosts/{postId}(+ body/main)  scoped to a board by the boardId field
+// memiBoardComments/{commentId}         scoped by the postId + boardId fields
+// memiBoardLikes/{likeId}               doc ID = `${postId}_${uid}` or `${commentId}_${uid}`
 //
-// 카테고리 없음 — boardId 가 곧 예전 category id.
-// posts/comments/likes 는 모두 최상위 flat 컬렉션이다. boardId(및 postId)가 이제
-// 경로가 아니라 문서 필드이므로, list/collectionGroup 쿼리에 대한 권한 검사가
-// 아래처럼 "쿼리의 등호(==) 필터가 그 필드를 상수로 고정해 주는가"에 의존한다.
-// (구버전의 collectionGroup carve-out은 더 이상 필요 없음 — memiBoardPosts가
-// 진짜 flat 컬렉션이라 작성자 교차조회도 일반 list 쿼리로 동작한다.)
+// No categories — boardId is the old category id.
+// posts/comments/likes are all top-level flat collections. Since boardId (and postId) are now
+// document fields rather than paths, permission checks on list/collectionGroup queries
+// depend, as below, on "whether the query's equality (==) filter pins that field to a constant".
+// (The old collectionGroup carve-out is no longer needed — memiBoardPosts is
+// a true flat collection, so cross-author lookups also work as regular list queries.)
 
 rules_version = '2';
 service cloud.firestore {
@@ -20,9 +20,9 @@ service cloud.firestore {
     function isSignedIn() {
       return request.auth != null;
     }
-    // 호스트가 다른 기능(예: 손님 대기열)에서 익명 로그인을 켜둔 경우에도
-    // 게시판 콘텐츠 생성(글/댓글/좋아요)만은 기본적으로 막는다 — 읽기·isSignedIn()
-    // 전반은 그대로 두고, 아래 3개 create 규칙에서만 이 함수를 쓴다.
+    // Even if the host app enables anonymous sign-in for another feature (e.g. a guest queue),
+    // block creating board content (posts/comments/likes) by default — reads and isSignedIn()
+    // in general are left as-is; this function is used only in the 3 create rules below.
     function isBoardWriter() {
       return isSignedIn() && request.auth.token.firebase.sign_in_provider != 'anonymous';
     }
@@ -48,8 +48,8 @@ service cloud.firestore {
     function commentPath(commentId) {
       return /databases/$(database)/documents/memiBoardComments/$(commentId);
     }
-    // 댓글 이미지 1장. 없거나 빈 목록도 허용한다. 경로는 그 댓글 폴더만.
-    // 게시물 컬렉션 이름을 바꾼 호스트는 memiBoardPosts 접두사도 맞춘다.
+    // One comment image. A missing or empty list is also allowed. The path must be that comment's folder.
+    // Host apps that renamed the posts collection must also update the memiBoardPosts prefix.
     function commentImageEntryValid(img, postId, commentId) {
       return img.keys().hasOnly(['name', 'url', 'path', 'size', 'type'])
         && img.name is string
@@ -82,7 +82,7 @@ service cloud.firestore {
         && likeId == request.resource.data.postId + '_' + request.auth.uid;
     }
     function isValidCommentLike(likeId) {
-      // 예전 댓글은 boardId 가 없을 수 있다. 스푸핑 방지는 댓글의 postId + 부모 글 boardId 로 한다.
+      // Older comments may lack boardId. Spoofing is prevented via the comment's postId + the parent post's boardId.
       return request.resource.data.keys().hasOnly(['uid', 'postId', 'boardId', 'createdAt', 'commentId', 'target'])
         && request.resource.data.target == 'comment'
         && request.resource.data.commentId is string
@@ -115,7 +115,7 @@ service cloud.firestore {
       return isBoardStaff() && isAllowedStaffForBoard(boardId);
     }
     // A visibility transition freezes new content until every listed flag is synchronized.
-    // 공지(pinned·pinnedAt)는 매니저 전용 갱신으로만 바뀐다 — 작성자의 일반 수정으로는 못 바꾼다.
+    // Notices (pinned, pinnedAt) change only via manager-only updates — an author's regular edit cannot change them.
     function postPinUnchanged() {
       return request.resource.data.get('pinned', false) == resource.data.get('pinned', false)
         && request.resource.data.get('pinnedAt', null) == resource.data.get('pinnedAt', null);
@@ -183,8 +183,8 @@ service cloud.firestore {
         && request.resource.data.viewCount is int
         && request.resource.data.viewCount == resource.data.get('viewCount', 0) + 1;
     }
-    // 답글 생성/삭제 batch에서는 대상이 최상위(root) 댓글이라 작성자가 아닌 사람도
-    // replyCount만 ±1 갱신할 수 있어야 한다 — 아니면 답글 작성 자체가 배치 전체로 막힌다.
+    // In a reply create/delete batch the target is a root comment, so users other than its author
+    // must be able to update only replyCount by ±1 — otherwise the whole batch, and thus writing a reply, is blocked.
     function isReplyCountUpdate() {
       return isSignedIn()
         && request.resource.data.diff(resource.data).affectedKeys().hasOnly(['replyCount'])
@@ -193,30 +193,30 @@ service cloud.firestore {
         && (request.resource.data.replyCount == resource.data.get('replyCount', 0) + 1
           || request.resource.data.replyCount == resource.data.get('replyCount', 0) - 1);
     }
-    // 프로필 이름 변경 시 나를 답글 대상으로 가리키는 다른 사용자의 댓글에
-    // 복제된 replyToName만 동기화할 수 있다. 작성자/본문 등 다른 필드는 불변이다.
+    // When a profile name changes, only the copied replyToName in other users' comments that
+    // point to me as the reply target may be synced. Author, body, and other fields are immutable.
     function isReplyTargetProfileUpdate() {
       return isSignedIn()
         && resource.data.replyToUid == request.auth.uid
         && request.resource.data.replyToUid == resource.data.replyToUid
         && request.resource.data.diff(resource.data).affectedKeys().hasOnly(['replyToName']);
     }
-    // data.boardId 는 이제 문서 필드다. list 쿼리에서 이 함수가 안전하게 평가되려면:
-    //  - isBoardAdmin()/isBoardStaff() 만으로 true 가 되는 경우는 항상 OK
-    //    (request.auth.uid 기준 get() 이라 문서 내용과 무관하게 항상 평가 가능)
-    //  - (isBoardStaff() && canWriteBoard(data.boardId)) 분기에 기대려면 쿼리에
-    //    where('boardId','==', b) 동등 필터가 있어야 한다 — 그래야 Firestore가
-    //    potential result set 전체에 대해 data.boardId == b 임을 정적으로 증명하고
-    //    get(boardSettingsPath(b))를 상수 조회로 안전하게 실행할 수 있다.
+    // data.boardId is now a document field. For this function to evaluate safely in list queries:
+    //  - cases where isBoardAdmin()/isBoardStaff() alone yields true are always OK
+    //    (get() is keyed on request.auth.uid, so it can always be evaluated regardless of document contents)
+    //  - relying on the (isBoardStaff() && canWriteBoard(data.boardId)) branch requires the query
+    //    to have a where('boardId','==', b) equality filter — that lets Firestore
+    //    statically prove data.boardId == b for the entire potential result set and
+    //    safely run get(boardSettingsPath(b)) as a constant lookup.
     function canReadPost(data) {
       return (data.get('listed', true) == true && data.isPublished == true)
         || (isSignedIn() && request.auth.uid == data.authorUid)
         || isBoardAdmin()
         || isBoardManager(data.boardId);
     }
-    // 공개 피드·작성자 댓글 목록은 listed==true 동등 필터로 숨김 보드 댓글을 뺀다.
-    // 글 상세(postId == 상수)에서는 부모 글을 읽을 수 있으면 숨김 댓글도 볼 수 있다
-    // (작성자가 담당 스태프 메모를 읽는 경우).
+    // Public feeds and author comment lists exclude hidden-board comments with a listed==true equality filter.
+    // On a post detail (postId == constant), anyone who can read the parent post can also see hidden comments
+    // (e.g. an author reading an assigned staff memo).
     function canReadComment(data) {
       return data.listed == true
         || (isSignedIn() && request.auth.uid == data.authorUid)
@@ -231,7 +231,7 @@ service cloud.firestore {
     }
 
     match /memiBoardUsers/{uid} {
-      // 이메일 말고는 다 공개 프로필 정보다 — 이메일은 private 서브컬렉션에 따로 둔다.
+      // Everything except email is public profile info — email is kept separately in a private subcollection.
       allow read: if true;
       allow create: if isSignedIn()
         && request.auth.uid == uid
@@ -252,7 +252,7 @@ service cloud.firestore {
               && request.resource.data.moderationBlockCount
                 == resource.data.get('moderationBlockCount', 0) + 1
             )
-            // 0.47.0 이하: 호출 전에 확정 횟수를 1 올린다.
+            // 0.47.0 and earlier: increment the confirmed count by 1 before the call.
             || (
               request.resource.data.diff(resource.data).affectedKeys()
                 .hasOnly(['aiWritingCount', 'aiWritingWindowAt', 'updatedAt'])
@@ -273,8 +273,8 @@ service cloud.firestore {
                 )
               )
             )
-            // 0.47.1+: 호출 전에 예약만 잡고, 성공하면 확정한다. 실패하면 예약만 내린다.
-            // 확정 횟수는 1씩만 오르고, 클라이언트가 내리지는 못한다.
+            // 0.47.1+: only reserve before the call, and confirm on success. On failure, only release the reservation.
+            // The confirmed count only increases by 1 at a time and cannot be decreased by the client.
             || (
               request.resource.data.diff(resource.data).affectedKeys()
                 .hasOnly(['aiWritingPending', 'updatedAt'])
@@ -312,23 +312,23 @@ service cloud.firestore {
             )
           ));
 
-      // 다른 작성자에 대해 나만 보는 개인 메모. 문서 ID가 targetUid라 대상당 하나로
-      // 고정된다. 관리자도 못 읽는다 — 모더레이션용이 아니라 순전히 본인 참고용이다.
+      // A private memo about another author, visible only to me. The doc ID is targetUid, so there is
+      // one per target. Even admins can't read it — it is purely for personal reference, not moderation.
       match /memos/{targetUid} {
         allow read, write: if isSignedIn() && request.auth.uid == uid;
       }
 
-      // 이메일만 담는 비공개 서브컬렉션. 본인·관리자만 읽고 쓴다.
+      // Private subcollection holding only the email. Only the user and admins can read and write.
       match /private/{docId} {
         allow read, write: if isBoardAdmin() || (isSignedIn() && request.auth.uid == uid);
       }
     }
 
-    // 구 memiBoards/{boardId} stub + memiBoards/{boardId}/settings/config 를 하나로 합친
-    // 캐노니컬 보드 문서. 목록 렌더링과 권한 검사가 모두 이 문서 하나만 읽는다.
-    // create/update 를 분리한 이유: update 쪽 staff 분기가 resource.data(기존 값)를
-    // 참조하는데, create 시점엔 resource 가 없어 하나로 묶으면 그 분기가 에러로
-    // 평가된다 — 구버전에서도 보드 생성 자체는 admin 전용이었으므로 분리가 자연스럽다.
+    // Canonical board document that merges the old memiBoards/{boardId} stub + memiBoards/{boardId}/settings/config.
+    // List rendering and permission checks both read only this one document.
+    // Why create/update are separate: the staff branch on update references resource.data (existing values),
+    // but resource doesn't exist at create time, so combining them would make that branch evaluate
+    // to an error — board creation was admin-only in older versions too, so separating them is natural.
     match /memiBoardSettings/{boardId} {
       allow read: if true;
       allow create: if isBoardAdmin();
@@ -381,17 +381,17 @@ service cloud.firestore {
     }
 
     match /memiBoardComments/{commentId} {
-      // 공개 피드·작성자 댓글 목록은 where('listed','==',true) 로 숨김 보드 댓글을 걸러낸다.
-      // 글 상세는 postId 동등 필터라 부모 글 권한(canReadPost)으로 숨김 댓글도 읽을 수 있다.
+      // Public feeds and author comment lists filter out hidden-board comments with where('listed','==',true).
+      // Post details use a postId equality filter, so hidden comments can be read via parent post permission (canReadPost).
       allow read: if isBoardAdmin() || canReadComment(resource.data);
 
       allow create: if isBoardWriter()
         && request.resource.data.postId is string
         && request.resource.data.boardId is string
-        // boardId 는 클라이언트가 채우는 비정규화 필드라 스푸핑이 가능하다 — 실제
-        // 글의 boardId 와 다른 값을 채워 commentWriteRole 이 느슨한 다른 보드인 척
-        // canWriteBoardComment() 를 우회하는 것을 막기 위해 부모 글의 실제 boardId 와
-        // 일치하는지 확인한다(비용: 댓글 생성마다 get() 1회 추가).
+        // boardId is a denormalized field filled by the client and can be spoofed — to prevent
+        // filling in a value different from the post's actual boardId to pose as another board with a looser
+        // commentWriteRole and bypass canWriteBoardComment(), check that it matches the parent post's actual
+        // boardId (cost: one extra get() per comment creation).
         && get(postPath(request.resource.data.postId)).data.boardId == request.resource.data.boardId
         && canWriteBoardComment(request.resource.data.boardId)
         && boardWritesOpen(request.resource.data.boardId)
@@ -422,14 +422,14 @@ service cloud.firestore {
         );
     }
 
-    // 좋아요 토글 전용 flat 컬렉션. 문서ID 관례 = `${targetId}_{uid}`.
-    // 본문: target 없음(레거시) + 필드 4개. 댓글: target=='comment' + commentId.
+    // Flat collection for like toggles only. Doc ID convention = `${targetId}_{uid}`.
+    // Body: no target (legacy) + 4 fields. Comments: target=='comment' + commentId.
     match /memiBoardLikes/{likeId} {
-      // "내가 좋아요한 글/댓글" 쿼리(where uid==auth.uid)를 위해 자기 것은 항상 읽을 수
-      // 있다. 그 외에는 구버전과 동일하게, 해당 글을 읽을 수 있는 사람이면 (uid를
-      // 정확히 알고 있는 한) 개별 get() 으로 좋아요 여부를 확인할 수 있다.
-      // resource == null: 아직 없는 좋아요 문서를 트랜잭션에서 get 할 때.
-      // 없으면 resource.data 접근이 실패해 일반 사용자의 첫 좋아요가 permission-denied 가 된다.
+      // Your own likes are always readable for the "posts/comments I liked" query (where uid==auth.uid).
+      // Otherwise, as in older versions, anyone who can read the post can check whether a like exists
+      // via an individual get() (as long as they know the exact uid).
+      // resource == null: when getting a like document that doesn't exist yet in a transaction.
+      // Without this, accessing resource.data fails and a regular user's first like becomes permission-denied.
       allow read: if isBoardAdmin() || (isSignedIn() && resource == null)
         || (isSignedIn() && request.auth.uid == resource.data.uid)
         || (resource != null && canReadPost(get(postPath(resource.data.postId)).data))
@@ -444,10 +444,10 @@ service cloud.firestore {
 
       allow delete: if isBoardAdmin() || (isSignedIn()
         && (request.auth.uid == resource.data.uid || canDeleteLike(resource.data)));
-      // update 는 허용하지 않음 — 토글은 항상 create-or-delete.
+      // update is not allowed — toggling is always create-or-delete.
     }
 
-    // 글 신고. 문서ID = `${postId}_{uid}`. 내용은 본인·스태프만 읽는다.
+    // Post reports. Doc ID = `${postId}_{uid}`. Contents are readable only by the reporter and staff.
     match /memiBoardReports/{reportId} {
       allow read: if (isSignedIn() && resource == null)
         || (isSignedIn() && request.auth.uid == resource.data.uid)