hikoutei 0.4.3 → 0.4.6

package/README.ja.md

@@ -4,11 +4,16 @@
 
 # Hikoutei
 
-**Google Sheets を利用する MVP 向けの型付きリポジトリと安全な書き込みレイヤー**
+**SQLite でアプリは高速に、Google Sheets でワークフローを見えるままに。**
 
-<a href="https://www.npmjs.com/package/hikoutei">npm パッケージ</a> ·
-<a href="https://github.com/ManddarinShop/Hikoutei/issues">Issues</a> ·
-<a href="docs/quick-start.md">クイックスタート</a>
+Google Sheets を利用する MVP 向けの型付きリポジトリであり、安全な書き込み
+レイヤー: アプリケーションは型付きエンティティでローカル SQLite を読み書きし、
+コミットされた変更は、人が確認して軽くコラボレーションできるよう Google
+Sheets へ非同期で投影されます。
+
+<a href="https://www.npmjs.com/package/hikoutei">npm</a> ·
+<a href="docs/quick-start.md">クイックスタート</a> ·
+<a href="https://github.com/ManddarinShop/Hikoutei/issues">Issues</a>
 
 [![npm version](https://img.shields.io/npm/v/hikoutei?style=flat-square)](https://www.npmjs.com/package/hikoutei)
 [![license](https://img.shields.io/npm/l/hikoutei?style=flat-square)](LICENSE)
@@ -16,39 +21,23 @@
 
 </div>
 
-Hikoutei は、TypeScript と Node.js のアプリケーションで Google Sheets を
-MVP や社内ワークフローの人間向けの画面として利用できるようにします。
-アプリケーションは型付きエンティティとローカル SQLite を使い、サービス
-アカウントの Google Sheets provider を通して変更を Google Sheets へ非同期に
-届けられます。
-
-Hikoutei の対象は意図的に限定されています。汎用データベースの代替、
-Prisma/JPA のクローン、汎用 Google Sheets API ラッパーを目的としていません。
-
-## Hikoutei が提供するもの
+## Hikoutei とは
 
-- エンティティ中心のライフサイクル: 作成、検索、変更、永続化、削除、flush。
-- Sheet データに対する型付きフィールドマッピングとランタイム検証。
-- リモートのスプレッドシート要求を待たないローカル SQLite の読み取り。
-- 人による確認や軽い共同作業に使える非同期 Google Sheets ビュー。
-- 予期しないスキーマ変更や新しいデータを上書きする問題への保護。
-
-## インストール
+Hikoutei は、TypeScript アプリケーションにローカル SQLite を基盤とする型付き
+エンティティ API を提供し、コミットされた変更を Google Sheets へ非同期に
+同期します。
 
-プロジェクトと npm パッケージ名は `hikoutei` です。
-
-```sh
-npm install hikoutei @mikro-orm/core @mikro-orm/sql
-```
+通常の読み書きでは、アプリケーションは Google Sheets を待ちません。Sheets は
+確認・運用・軽いコラボレーションのための画面として残ります。
 
-MikroORM パッケージはルートパッケージの optional peer dependency です。現在の
-SQLite provider が内部で利用しますが、ルート public API に MikroORM 型は公開
-されません。
+> Hikoutei は生の Sheets API ラッパーではなく、PostgreSQL の代替でもなく、
+> Google Sheets を権威あるアプリケーションデータベースとして扱いません。
+> SQLite が真実の源泉であり、Sheets は人向けの画面です。
 
 ## クイックスタート
 
-エンティティ定義と SQLite の lifecycle はルート API だけを使います。Sheet route、
-provider credential、provisioning、polling は内部 service bootstrap の責務です。
+スカラーエンティティを定義し、リクエストローカルなマネージャーでローカル
+SQLite の権威を利用します。
 
 ```ts
 import { createTypedSheets, defineTypedSheetsEntity } from "hikoutei";
@@ -76,97 +65,160 @@ user.name = "Ada Lovelace";
 await em.flush();
 ```
 
-`createTypedSheets()` はローカルの entity table だけを準備し、Google Sheets へ接続
-しません。内部 sync service が mapping を登録してタブを provision し、outbound
-worker と User_Input polling を開始します。service mode では `flush()` が entity、
-canonical state、durable outbox を SQLite transaction としてコミットし、リモート
-Sheet への配信は非同期に行います。
+**シートには何が起きるのか?** 書き込みは即座にローカル SQLite へコミット
+されます — アプリケーションのリクエストは Google を待ちません。同期サービスが
+有効な場合、Hikoutei は後でエンティティを登録済みの Google Sheet へバック
+グラウンドで投影します。シート上で行われた人の編集は観察・検証され、SQLite
+へ受け入れられるか競合として記録されるかのどちらかで、決して静かに上書き
+されません。
+
+## Hikoutei を使う理由
+
+- シートの行を手動で変換する代わりに、型付きエンティティを定義する。
+- Google Sheets を待たずにローカル SQLite で読み書きする。
+- コミットされた変更を Sheets へバックグラウンドで同期する。
+- 予期しない列の変更や重複ヘッダーを検出する。
+- 競合時に新しいシート編集を上書きしない。
 
 ## Hikoutei が適しているケース
 
-- スプレッドシートがプロダクトの業務フローの一部である MVP とプロトタイプ。
-- 社内ツールと低トラフィックの管理アプリケーション。
-- 型付きのアプリケーションデータを保ちながら、Sheets を人が簡単に確認したい
-  チーム。
-- ローカル SQLite を使うことができ、Sheets の非同期更新を受け入れられるサービス。
+Hikoutei は以下のケースに適しています。
+
+- 製品ワークフローの一部にスプレッドシートがある MVP・プロトタイプ
+- 社内ツールや低トラフィックの管理アプリケーション
+- 人が Sheets を簡単に確認しつつ、型付きのアプリケーションデータを扱いたい
+  チーム
+- SQLite をローカルで使い、非同期のシート更新を受け入れられるサービス
 
-## 別のツールを選ぶべきケース
+## 他のツールを選ぶべきケース
 
-次の要件がある場合は、通常のデータベースと Google API の直接利用を検討してください。
+次の要件がある場合は、通常のデータベースと Google API を直接使ってください。
 
-- 複数行または複数サービスにまたがる強いトランザクション。
-- 高い書き込みスループット、または多数の同時書き込み。
-- 複雑なクエリ、JOIN、レポート処理。
-- マルチサーバーまたはマルチリージョンの調整。
-- Google Sheets で即時の read-after-write 整合性が必要。
-- Google Sheets をアプリケーションの主データベースにする必要がある。
+- 多くの行やサービスにまたがる強いトランザクション
+- 高い書き込みスループットや多数の同時ライター
+- 複雑なクエリ・JOIN・レポートワークロード
+- マルチサーバー・マルチリージョンでの調整
+- Google Sheets での読み取り直後の整合性
+- Google Sheets をアプリケーションの主要データベースとして使う場合
+
+## Hikoutei はあなたに合った抽象化か?
+
+Hikoutei は `google-spreadsheet` や `@googleapis/sheets` を置き換えるものでは
+ありません — その一段上に位置します。生のスプレッドシート操作だけが必要なら、
+API クライアントを直接使ってください。
+
+| 機能 | Hikoutei | google-spreadsheet | @googleapis/sheets |
+| --- | :-: | :-: | :-: |
+| 型付きエンティティモデル | ✅ | ❌ | ❌ |
+| 高速なローカルアプリケーション読み取り | ✅ | ❌ | ❌ |
+| Sheets への非同期投影 | ✅ | ❌ | ❌ |
+| 永続的な書き込み再試行と重複排除 | ✅ | ❌ | ❌ |
+| 競合を考慮したシート更新 | ✅ | ❌ | ❌ |
+| 行・セルの直接操作 | 限定的 | ✅ | ✅ |
+| Google Sheets API へのフルアクセス | Provider 経由 | 部分的 | ✅ |
 
 ## Google Sheets の設定
 
-Google Sheets の同期は service-side の責務です。推奨経路はサービスアカウントの
-`googleSheetsApi` provider で、ひとつのサービスアカウントがタブの provisioning、
-outbound effect の書き込み（高速 append、guarded update/delete、レシート、
-応答喪失の復旧）、テーブル読み取り、行アンカー、ユーザー編集の観察をすべて
-行います。アプリケーションは provider クライアントを import したり、Sheet route
-を `createTypedSheets()` に渡したりしません。
-
-1. `https://www.googleapis.com/auth/spreadsheets` スコープを持つ Google Cloud
-   サービスアカウントを作成し、対象スプレッドシートをそのメールアドレスに
-   **編集者**として共有します。provider がタブ作成、effect 行とレシート記録、
-   行アンカー管理を行うため、閲覧者権限では不十分です。Cloud プロジェクトで
-   Google Sheets API を有効化します。
-2. サービスアカウントキーのファイルパスをサーバーの
-   `GOOGLE_APPLICATION_CREDENTIALS` に置き、スプレッドシート ID はコミットされない
-   シークレットストアに保管します。キーをブラウザコードや Git に入れないでください。
-3. `googleSheetsApi` で内部 sync bootstrap を起動します。登録タブのヘッダーを
-   作成・検証した後、outbox 配信と User_Input polling を開始します。
-
-シートの整合性はリクエスト間の Sheet トランザクションから生まれるのではなく、
-隠された effect-receipt タブ、effect-id/payload-hash の重複排除、SQLite の
-durable outbox、フェンシング、フィールド単位の compare-and-set 証拠、
-postcondition 復旧から生まれます。provider は資格情報・スプレッドシート ID・
-URL・payload をログに残さず、要求開始間隔をクラスごと（読み取り/書き込み）
-1,100ms に調整して Google の quota window を守ります。`flush()` はローカル
-コミットのみを意味し、配信は非同期で、すべての書き込みはレシートで記録され、
-同じ effect worker が復旧します。
-
-追跡される live シナリオはこの provider で実行されます。
-[docs/sync-bulk-write-benchmark.md](docs/sync-bulk-write-benchmark.md) の
-10,000 行 append と update/delete の live 証拠も同じ REST 経路です。
-`scripts/bench/` の生トランスポート実験はレシート/CAS のない unguarded 経路
-なので、worker 経由の測定までは性能値を検証済みと見なさないでください。live
-呼び出しは opt-in で、通常の検証は fake provider と SQLite fixture を使います。
-
-従来の Apps Script Gateway と `appsScript`/`googleApiWorker` オプションは削除され、
-上記のサービスアカウント provider が唯一の同期経路です。詳しい設定と
-トラブルシューティングは [クイックスタート](docs/quick-start.md) を参照してください。
+Google Sheets の同期はサービス側の関心事です。アプリケーションは provider
+クライアントを import したり、`createTypedSheets()` にシートルートを渡したり、
+書き込みごとに操作を選んだりしません。同期ランタイムはサービスアカウントを
+使う単一の Google Sheets API provider(内部 `googleSheetsApi` bootstrap オプ
+ション)を使用します — Apps Script のデプロイは不要です。
+
+### 環境変数による同期の自動開始
+
+スプレッドシートの URL を環境変数に設定すると、`createTypedSheets()` が内部で
+Sheets 同期を開始します — `flush()` はセットアップコードなしで outbox
+ワーカー経由で Google Sheets に流れます:
+
+```sh
+HIKOUTEI_SYNC_SPREADSHEET_URL=https://docs.google.com/spreadsheets/d/<ID>/edit
+GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/service-account.json
+```
+
+```ts
+const hikoutei = await createTypedSheets({ dbName: "./hikoutei.sqlite", entities: [User] });
+```
+
+`HIKOUTEI_SYNC_SPREADSHEET_URL` がない場合、`createTypedSheets()` はローカル
+専用 (SQLite) のままです。起動失敗は明確なメッセージで診断されます: URL の
+不正、資格情報ファイルの欠落・不正、スプレッドシートに共有されていない
+サービスアカウント (共有すべきメールアドレスをエラーが教えてくれます)。
+
+### Service-account provider (googleSheetsApi)
+
+1. **サービスアカウントを作成する。** Cloud プロジェクトで Google Sheets API
+   を有効化し、`https://www.googleapis.com/auth/spreadsheets` スコープの
+   サービスアカウントを作成して、対象スプレッドシートをそのメールアドレスに
+   **編集者(Editor)**として共有します。provider がタブを作成し、効果行と
+   receipt レコードを書き、行アンカーを管理するため、閲覧者権限では不十分
+   です。
+2. **キーはサーバー側に置く。** サービスアカウントのキーパスはサーバーの
+   `GOOGLE_APPLICATION_CREDENTIALS` に、スプレッドシート ID は追跡されない
+   シークレットストアに置きます。キーをブラウザコードや Git に入れないで
+   ください。
+3. **内部 sync bootstrap を起動する。** `googleSheetsApi` を設定すると、
+   登録済みタブのヘッダーを作成・検証した後、outbox 配信と User_Input ポー
+   リングを開始します。
+
+Hikoutei は、永続的なローカル outbox・冪等な配信・競合を考慮した更新を使う
+ため、一時的な API 障害でコミット済みのアプリケーション書き込みが失われる
+ことはありません。provider は資格情報・スプレッドシート ID・URL・ペイロードを
+ログに残さず、Google の割り当て枠に収まるようリクエスト開始間隔を調整します。
+詳細な状態機械と復旧ルールは[内部整合性モデル](docs/internal-consistency-model.md)を
+参照してください。
+
+ライブの Google 呼び出しはオプトインであり、通常の検証経路はフェイク
+provider と SQLite フィクスチャです。詳細なセットアップとトラブルシューティン
+グは[クイックスタート](docs/quick-start.md)を参照してください。
+
+## インストール
+
+プロジェクト名と npm パッケージ名はどちらも `hikoutei` です。現在の組み込み
+SQLite provider は MikroORM を必要とします。
+
+```sh
+npm install hikoutei @mikro-orm/core @mikro-orm/sql
+```
+
+MikroORM は実装の詳細であり、Hikoutei の公開エンティティ API には現れません。
 
 ## ドキュメント
 
-- [クイックスタート](docs/quick-start.md) — インストール、ORM lifecycle、service-side sync 設定。
-- [アーキテクチャ](docs/architecture.md) — ローカルストアと Sheet ビューの関係。
-- [書き込みと同期の流れ](docs/write-and-synchronization-flow.md) — 非同期配信と復旧動作。
-- [開発ガイド](docs/development.md) — ローカル開発とテストコマンド。
-- [ベンチマーク記録](docs/sync-bulk-write-benchmark.md) — 日付ごとの測定結果と制約。
+- [クイックスタート](docs/quick-start.md) — インストール、ORM ライフサイクル、
+  サービス側の同期設定
+- [アーキテクチャ](docs/architecture.md) — ローカルストアとシートビューの関係
+- [書き込みと同期フロー](docs/write-and-synchronization-flow.md) — 非同期配信と
+  復旧動作
+- [内部整合性モデル](docs/internal-consistency-model.md) — 永続的な outbox、
+  冪等な配信、競合を考慮した更新
+- [開発](docs/development.md) — ローカル開発とテストコマンド
+- [ベンチマークノート](docs/sync-bulk-write-benchmark.md) — 日付付きの測定と
+  その限界
 
 ## 制限事項
 
-- Google Sheets にはクォータ、レイテンシー、API のレート制限があります。
-- Sheet の更新は非同期なので、アプリケーションはローカル状態を読み取るべきです。
-- SQLite はサービスにローカルなもので、分散調整レイヤーではありません。
-- スキーマ変更、手動編集、競合する変更に対する運用方針は、アプリケーション側で
-  別途決める必要があります。
+- Google Sheets には割り当て枠・レイテンシ・API レート制限があります。
+- シートの更新は非同期であり、アプリケーションはローカル状態を読むべきです。
+- SQLite はサービスのローカルのみであり、分散調整レイヤーではありません。
+- スキーマ変更・手動編集・競合更新には、依然としてアプリケーションの運用
+  ポリシーが必要です。
+
+## プロジェクトステータス
+
+Hikoutei は活発に開発中です。エンティティ API は利用可能ですが、シート編集の
+取り込みと競合表示はまだ発展途上です。マイナーバージョンのアップグレード前に
+リリースノートを確認してください。
 
 ## ロードマップ
 
-- Google Sheets から意図的なユーザー編集を取り込む機能を完成させる。
-- update/delete の競合処理と表示を改善する。
-- レジストリと直接 provider デプロイ用のセットアップツールを追加する。
-- 公開パッケージのリリースを安定化する。
+- Google Sheets からの意図的なユーザー編集の取り込みを完了する
+- 更新・削除の競合処理と表示を改善する
+- レジストリと直接 provider デプロイのセットアップツールを追加する
 
-現在の作業については [open issues](https://github.com/ManddarinShop/Hikoutei/issues)
-を参照してください。
+現在の作業は[オープンな Issues](https://github.com/ManddarinShop/Hikoutei/issues)を
+参照してください。
 
 ## ライセンス
 
-Hikoutei は [MIT License](LICENSE) の下で公開されています。
+Hikoutei は [MIT ライセンス](LICENSE)で公開されています。

package/README.ko.md

@@ -4,11 +4,15 @@
 
 # Hikoutei
 
-**Google Sheets 기반 MVP를 위한 타입 안전 리포지토리 및 안전한 쓰기 계층**
+**SQLite로 앱은 빠르게, Google Sheets로 업무 흐름은 눈에 보이게.**
 
-<a href="https://www.npmjs.com/package/hikoutei">npm 패키지</a> ·
-<a href="https://github.com/ManddarinShop/Hikoutei/issues">이슈</a> ·
-<a href="docs/quick-start.md">빠른 시작</a>
+Google Sheets 기반 MVP를 위한 타입 안전 리포지토리이자 안전한 쓰기 계층:
+애플리케이션은 타입이 지정된 엔티티로 로컬 SQLite를 읽고 쓰고, 커밋된 변경은
+사람이 검토하고 가볍게 협업할 수 있도록 Google Sheets에 비동기로 투영됩니다.
+
+<a href="https://www.npmjs.com/package/hikoutei">npm</a> ·
+<a href="docs/quick-start.md">빠른 시작</a> ·
+<a href="https://github.com/ManddarinShop/Hikoutei/issues">이슈</a>
 
 [![npm version](https://img.shields.io/npm/v/hikoutei?style=flat-square)](https://www.npmjs.com/package/hikoutei)
 [![license](https://img.shields.io/npm/l/hikoutei?style=flat-square)](LICENSE)
@@ -16,39 +20,22 @@
 
 </div>
 
-Hikoutei는 TypeScript와 Node.js 애플리케이션에서 Google Sheets를 MVP 또는
-내부 업무 흐름의 사람이 읽기 쉬운 화면으로 사용할 수 있게 합니다. 애플리케이션은
-타입이 지정된 엔티티와 로컬 SQLite를 사용하고, 서비스 계정 기반 Google
-Sheets provider를 통해 변경 내용을 Google Sheets에 비동기적으로 전달할 수
-있습니다.
-
-Hikoutei의 범위는 의도적으로 작습니다. 범용 데이터베이스 대체재, Prisma/JPA
-클론, 범용 Google Sheets API 래퍼를 목표로 하지 않습니다.
-
-## Hikoutei가 제공하는 것
+## Hikoutei란 무엇인가?
 
-- 엔티티 중심 생명주기: 생성, 조회, 변경, `persist`, `remove`, `flush`.
-- Sheet 데이터에 대한 타입 필드 매핑과 런타임 검증.
-- 원격 스프레드시트 요청을 기다리지 않는 로컬 SQLite 조회.
-- 사람이 검토하고 가볍게 협업할 수 있는 비동기 Google Sheets 뷰.
-- 예상하지 못한 스키마 변경과 최신 데이터를 덮어쓰는 문제에 대한 보호.
-
-## 설치
+Hikoutei는 TypeScript 애플리케이션에 로컬 SQLite를 기반으로 한 타입 지정
+엔티티 API를 제공하고, 커밋된 변경을 Google Sheets에 비동기로 동기화합니다.
 
-프로젝트와 npm 패키지 이름은 모두 `hikoutei`입니다.
-
-```sh
-npm install hikoutei @mikro-orm/core @mikro-orm/sql
-```
+일반적인 읽기와 쓰기에서 애플리케이션은 Google Sheets를 기다리지 않습니다.
+Sheets는 검토, 운영, 가벼운 협업을 위한 화면으로 남습니다.
 
-MikroORM 패키지는 루트 패키지의 선택적 peer dependency입니다. 현재 기본
-SQLite provider가 내부적으로 사용하지만 루트 public API에는 MikroORM 타입이
-노출되지 않습니다.
+> Hikoutei는 원시 Sheets API 래퍼가 아니며, PostgreSQL의 대체재도 아니고,
+> Google Sheets를 권위 있는 애플리케이션 데이터베이스로 취급하지 않습니다.
+> SQLite가 진실의 원천이고, Sheets는 사람을 위한 화면입니다.
 
 ## 빠른 시작
 
-엔티티 정의와 SQLite lifecycle은 루트 API만 사용합니다. Sheet route,
-provider credential, provisioning, polling은 내부 service bootstrap의 책임입니다.
+스칼라 엔티티를 정의하고 요청-로컬 매니저를 통해 로컬 SQLite authority를
+사용합니다.
 
 ```ts
 import { createTypedSheets, defineTypedSheetsEntity } from "hikoutei";
@@ -76,100 +63,157 @@ user.name = "Ada Lovelace";
 await em.flush();
 ```
 
-`createTypedSheets()`는 로컬 entity table만 준비하며 Google Sheets에 연결하지
-않습니다. 내부 sync service가 mapping을 등록하고 탭을 provisioning한 뒤
-outbound worker와 User_Input polling을 시작합니다. service mode에서
-`flush()`는 entity, canonical state, durable outbox를 SQLite transaction으로
-커밋하고 원격 Sheet 전달은 비동기로 수행합니다.
+**시트에는 무슨 일이 일어날까?** 쓰기는 즉시 로컬 SQLite에 커밋됩니다 —
+애플리케이션 요청은 Google을 기다리지 않습니다. 동기화 서비스가 활성화되면
+Hikoutei는 나중에 엔티티를 등록된 Google Sheet에 백그라운드로 투영합니다.
+시트에서 이루어진 사람의 수정은 관찰되고 검증되어 SQLite로 수용되거나
+충돌로 기록되며, 절대 조용히 덮어쓰이지 않습니다.
 
-## Hikoutei를 사용하기 좋은 경우
+## Hikoutei를 쓰는 이유
 
-- 스프레드시트가 제품 업무 흐름의 일부인 MVP와 프로토타입.
-- 내부 도구와 저트래픽 관리 애플리케이션.
-- 타입이 지정된 애플리케이션 데이터를 유지하면서 사람이 Sheets를 쉽게
-  확인해야 하는 팀.
-- 로컬 SQLite를 사용할 수 있고 Sheets의 비동기 업데이트를 허용할 수 있는
-  서비스.
+- 시트 행을 수동으로 변환하는 대신 타입 지정 엔티티를 정의합니다.
+- Google Sheets를 기다리지 않고 로컬 SQLite로 읽고 씁니다.
+- 커밋된 변경을 Sheets에 백그라운드로 동기화합니다.
+- 예상치 못한 컬럼 변경과 중복 헤더를 감지합니다.
+- 충돌 중에 더 새로운 시트 수정을 덮어쓰지 않습니다.
 
-## 다른 도구를 선택해야 하는 경우
+## Hikoutei를 쓰기 좋은 때
 
-다음 요구사항이 있다면 일반적인 데이터베이스와 직접적인 Google API 사용을
-검토하세요.
+Hikoutei는 다음 상황에 잘 맞습니다.
 
-- 여러 행 또는 여러 서비스에 걸친 강한 트랜잭션.
-- 높은 쓰기 처리량 또는 많은 동시 작성자.
-- 복잡한 쿼리, 조인, 리포팅 작업.
-- 멀티 서버 또는 멀티 리전 조정.
-- Google Sheets에서 즉시 쓰기 후 읽기 일관성이 필요한 경우.
-- 애플리케이션의 기본 데이터베이스로 Google Sheets를 사용해야 하는 경우.
+- 제품 워크플로의 일부로 스프레드시트가 있는 MVP와 프로토타입
+- 내부 도구와 저트래픽 관리 애플리케이션
+- 사람들이 Sheets를 쉽게 확인하면서 타입 지정된 애플리케이션 데이터를
+  유지하려는 팀
+- SQLite를 로컬에서 사용하고 비동기 시트 업데이트를 수용할 수 있는 서비스
+
+## 다른 도구를 선택해야 할 때
+
+다음이 필요하다면 일반 데이터베이스와 Google API를 직접 사용하세요.
+
+- 여러 행이나 서비스에 걸친 강력한 트랜잭션
+- 높은 쓰기 처리량 또는 많은 동시 작성자
+- 복잡한 쿼리, 조인, 리포팅 워크로드
+- 멀티 서버·멀티 리전 조정
+- Google Sheets에서의 즉시 읽기-쓰기 일관성
+- Google Sheets를 애플리케이션의 주 데이터베이스로 사용
+
+## Hikoutei가 당신에게 맞는 추상화인가요?
+
+Hikoutei는 `google-spreadsheet`나 `@googleapis/sheets`를 대체하지 않습니다 —
+한 단계 위에 위치합니다. 원시 스프레드시트 접근만 필요하다면 API 클라이언트를
+직접 사용하세요.
+
+| 기능 | Hikoutei | google-spreadsheet | @googleapis/sheets |
+| --- | :-: | :-: | :-: |
+| 타입 지정 엔티티 모델 | ✅ | ❌ | ❌ |
+| 빠른 로컬 애플리케이션 읽기 | ✅ | ❌ | ❌ |
+| Sheets로의 비동기 투영 | ✅ | ❌ | ❌ |
+| 내구성 있는 쓰기 재시도와 중복 제거 | ✅ | ❌ | ❌ |
+| 충돌을 인지하는 시트 업데이트 | ✅ | ❌ | ❌ |
+| 행·셀 직접 조작 | 제한적 | ✅ | ✅ |
+| 전체 Google Sheets API 접근 | Provider 경유 | 부분적 | ✅ |
 
 ## Google Sheets 설정
 
-Google Sheets 동기화는 service-side의 책임입니다. 권장 경로는 서비스 계정
-기반 `googleSheetsApi` provider로, 하나의 서비스 계정으로 탭 provisioning,
-outbound effect 쓰기(빠른 append, guarded update/delete, receipt, 응답 유실
-복구), 테이블 읽기, 행 anchor, 사용자 편집 관찰을 모두 수행합니다.
-애플리케이션은 provider client를 import하거나 Sheet route를
-`createTypedSheets()`에 넘기지 않습니다.
-
-1. `https://www.googleapis.com/auth/spreadsheets` scope를 가진 Google Cloud
-   서비스 계정을 만들고, 대상 스프레드시트를 이메일로 **Editor** 권한으로
-   공유합니다. provider가 탭 생성, effect 행과 receipt 기록, 행 anchor 관리를
-   하므로 Viewer 권한으로는 부족합니다. Cloud 프로젝트에서 Google Sheets API를
-   활성화합니다.
-2. 서비스 계정 키 파일 경로를 서버의 `GOOGLE_APPLICATION_CREDENTIALS`에 두고,
-   스프레드시트 ID는 커밋되지 않는 시크릿 저장소에 보관합니다. 키를 브라우저
-   코드나 Git에 넣지 마세요.
-3. `googleSheetsApi`로 내부 sync bootstrap을 시작합니다. 등록된 탭의 헤더를
-   생성/검증한 뒤 outbox 전달과 User_Input polling을 시작합니다.
-
-시트 일관성은 요청 간 Sheet 트랜잭션에서 오지 않습니다. 숨겨진
-effect-receipt 탭, effect-id/payload-hash 중복 제거, SQLite durable outbox,
-fencing, 필드 단위 compare-and-set 증거, postcondition 복구에서 옵니다.
-provider는 자격 증명, 스프레드시트 ID, URL, payload를 로그에 남기지 않으며,
-요청 시작 간격을 클래스별(읽기/쓰기) 1,100ms로 조절해 Google quota window를
-지킵니다. `flush()`는 로컬 커밋만 의미하고 전달은 비동기이며, 모든 쓰기는
-receipt로 기록되고 같은 effect worker가 복구합니다.
-
-추적되는 live 시나리오는 이 provider로 실행됩니다.
-[docs/sync-bulk-write-benchmark.md](docs/sync-bulk-write-benchmark.md)의
-10,000행 append와 update/delete live 증거도 같은 REST 경로를 사용합니다.
-`scripts/bench/`의 원시 전송 실험은 receipt/CAS 없는 unguarded 경로이므로,
-worker를 통한 측정 전에는 성능 수치를 검증된 것으로 보지 마세요. live 호출은
-opt-in이며, 일반 검증은 fake provider와 SQLite fixture를 사용합니다.
-
-기존 Apps Script Gateway와 `appsScript`/`googleApiWorker` 옵션은 제거되어
-위 서비스 계정 provider가 유일한 동기화 경로입니다. 상세한 설정과 문제 해결
-방법은 [빠른 시작](docs/quick-start.md)에 설명되어 있습니다.
+Google Sheets 동기화는 서비스 측 관심사입니다. 애플리케이션은 provider
+클라이언트를 import하거나, Sheet 라우트를 `createTypedSheets()`에 넘기거나,
+쓰기마다 연산을 선택하지 않습니다. 동기화 런타임은 서비스 계정을 사용하는
+하나의 Google Sheets API provider(내부 `googleSheetsApi` bootstrap 옵션)를
+사용합니다 — Apps Script 배포가 없습니다.
+
+### 환경 변수 기반 동기화 자동 시작
+
+스프레드시트 URL을 환경 변수로 설정하면 `createTypedSheets()`가 내부적으로
+Sheets 동기화를 시작합니다 — `flush()`는 설정 코드 없이 outbox worker를 통해
+Google Sheets로 흘러갑니다:
+
+```sh
+HIKOUTEI_SYNC_SPREADSHEET_URL=https://docs.google.com/spreadsheets/d/<ID>/edit
+GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/service-account.json
+```
+
+```ts
+const hikoutei = await createTypedSheets({ dbName: "./hikoutei.sqlite", entities: [User] });
+```
+
+`HIKOUTEI_SYNC_SPREADSHEET_URL`이 없으면 `createTypedSheets()`는 로컬 전용
+(SQLite)으로 유지됩니다. 시작 실패는 명확한 메시지로 진단됩니다: 잘못된 URL,
+없거나 잘못된 자격 증명 파일, 스프레드시트에 공유되지 않은 서비스 계정
+(어떤 이메일을 공유해야 하는지 에러가 알려줍니다).
+
+### Service-account provider (googleSheetsApi)
+
+1. **서비스 계정을 만듭니다.** Cloud 프로젝트에서 Google Sheets API를
+   활성화하고, `https://www.googleapis.com/auth/spreadsheets` 스코프의
+   서비스 계정을 만든 뒤 대상 스프레드시트를 해당 이메일에 **편집자(Editor)**로
+   공유합니다. provider가 탭을 만들고, 효과 행과 receipt 기록을 쓰고, 행
+   anchor를 관리하므로 뷰어 권한으로는 부족합니다.
+2. **키를 서버 측에 둡니다.** 서비스 계정 키 경로를 서버의
+   `GOOGLE_APPLICATION_CREDENTIALS`에, 스프레드시트 ID는 추적되지 않는
+   비밀 저장소에 둡니다. 키를 브라우저 코드나 Git에 넣지 마세요.
+3. **내부 sync bootstrap을 기동합니다.** `googleSheetsApi`를 설정하면
+   등록된 탭의 헤더를 만들고 검증한 뒤 outbox 전달과 User_Input 폴링을
+   시작합니다.
+
+Hikoutei는 내구성 있는 로컬 outbox, 멱등 전달, 충돌을 인지하는 업데이트를
+사용하므로 일시적인 API 실패가 커밋된 애플리케이션 쓰기를 잃게 하지 않습니다.
+provider는 자격 증명, 스프레드시트 ID, URL, 페이로드를 로그에 남기지 않으며,
+Google 할당량 창 안에 머물도록 요청 시작 간격을 조절합니다. 상세 상태 머신과
+복구 규칙은 [내부 정합성 모델](docs/internal-consistency-model.md)을
+참고하세요.
+
+라이브 Google 호출은 opt-in이며, 일반적인 검증 경로는 fake provider와 SQLite
+fixture입니다. 자세한 설정과 문제 해결 단계는 [빠른 시작](docs/quick-start.md)을
+참고하세요.
+
+## 설치
+
+프로젝트와 npm 패키지 이름은 모두 `hikoutei`입니다. 내장 SQLite provider는
+현재 MikroORM을 필요로 합니다.
+
+```sh
+npm install hikoutei @mikro-orm/core @mikro-orm/sql
+```
+
+MikroORM은 구현 세부 사항이며 Hikoutei의 공개 엔티티 API에는 나타나지
+않습니다.
 
 ## 문서
 
-- [빠른 시작](docs/quick-start.md) — 설치, ORM lifecycle, service-side sync 설정.
-- [아키텍처](docs/architecture.md) — 로컬 저장소와 Sheet 화면의 관계.
+- [빠른 시작](docs/quick-start.md) — 설치, ORM 생명주기, 서비스 측 동기화 설정
+- [아키텍처](docs/architecture.md) — 로컬 저장소와 Sheet 화면이 맞물리는 방식
 - [쓰기 및 동기화 흐름](docs/write-and-synchronization-flow.md) — 비동기 전달과
-  복구 동작.
-- [개발 가이드](docs/development.md) — 로컬 개발 및 테스트 명령.
-- [벤치마크 기록](docs/sync-bulk-write-benchmark.md) — 날짜별 측정 결과와
-  한계.
+  복구 동작
+- [내부 정합성 모델](docs/internal-consistency-model.md) — 내구성 outbox,
+  멱등 전달, 충돌을 인지하는 업데이트
+- [개발](docs/development.md) — 로컬 개발 및 테스트 명령어
+- [벤치마크 노트](docs/sync-bulk-write-benchmark.md) — 날짜가 기록된 측정과
+  그 한계
+
+## 한계
+
+- Google Sheets에는 quota, 지연, API 요청 제한이 있습니다.
+- 시트 업데이트는 비동기이며, 애플리케이션은 로컬 상태를 읽어야 합니다.
+- SQLite는 서비스 로컬 전용이며 분산 조정 계층이 아닙니다.
+- 스키마 변경, 수동 편집, 충돌 업데이트에는 여전히 애플리케이션의 운영 정책이
+  필요합니다.
 
-## 제한사항
+## 프로젝트 상태
 
-- Google Sheets에는 quota, 지연 시간, API rate limit이 있습니다.
-- Sheet 업데이트는 비동기이므로 애플리케이션은 로컬 상태를 읽어야 합니다.
-- SQLite는 서비스에 로컬이며 분산 조정 계층이 아닙니다.
-- 스키마 변경, 수동 편집, 충돌하는 변경에 대한 운영 정책은 애플리케이션이
-  별도로 정해야 합니다.
+Hikoutei는 활발히 개발 중입니다. 엔티티 API는 사용 가능하지만, 시트 편집
+수집과 충돌 표시는 아직 발전 중입니다. 마이너 버전 업그레이드 전에 릴리스
+노트를 확인하세요.
 
 ## 로드맵
 
-- Google Sheets에서 의도적인 사용자 편집을 수집하는 기능 완성.
-- update/delete 충돌 처리와 표시 개선.
-- 레지스트리 및 직접 provider 배포를 위한 설정 도구 추가.
-- 공개 패키지 릴리스 안정화.
+- Google Sheets에서 의도적인 사용자 편집 수집 완성
+- 업데이트·삭제 충돌 처리와 표시 개선
+- 레지스트리 및 직접 provider 배포를 위한 설정 도구 추가
 
-현재 작업은 [open issues](https://github.com/ManddarinShop/Hikoutei/issues)
-에서 확인할 수 있습니다.
+현재 작업은 [오픈 이슈](https://github.com/ManddarinShop/Hikoutei/issues)를
+참고하세요.
 
 ## 라이선스
 
-Hikoutei는 [MIT License](LICENSE)로 배포됩니다.
+Hikoutei는 [MIT 라이선스](LICENSE)로 배포됩니다.