hikoutei 0.10.18-dev → 0.10.20-dev

package/README.ja.md

@@ -2,6 +2,8 @@
 
 <div align="center">
 
+<img src="assets/hikoutei-icon.png" alt="Hikoutei" width="220" />
+
 # Hikoutei
 
 **SQLite でアプリは高速に、Google Sheets でワークフローを見えるままに。**
@@ -12,7 +14,7 @@ Google Sheets を利用する MVP 向けの型付きリポジトリであり、
 Sheets へ非同期で投影されます。
 
 <a href="https://www.npmjs.com/package/hikoutei">npm</a> ·
-<a href="website/guide/quick-start.md">クイックスタート</a> ·
+<a href="https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/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)
@@ -34,7 +36,53 @@ Hikoutei は、TypeScript アプリケーションにローカル SQLite を基
 > Google Sheets を権威あるアプリケーションデータベースとして扱いません。
 > SQLite が真実の源泉であり、Sheets は人向けの画面です。
 
-## クイックスタート
+## Hikoutei を使う理由
+
+- シート行を手動で変換する代わりに、型付きエンティティを定義できます。
+- Google Sheets を待たずにローカル SQLite で読み書きできます。
+- コミットされた変更をバックグラウンドで Sheets に同期します。
+- 想定外の列変更や重複ヘッダーを検出します。
+- 競合時に新しいシート編集を上書きしません。
+
+Hikoutei は `google-spreadsheet` や `@googleapis/sheets` の代わりではなく、
+その一段上に位置します。生のスプレッドシートアクセスだけが必要なら API
+クライアントを直接使ってください。
+
+| 機能 | Hikoutei | google-spreadsheet | @googleapis/sheets |
+| --- | :-: | :-: | :-: |
+| 型付きエンティティモデル | ✅ | ❌ | ❌ |
+| 高速なローカルアプリ読み取り | ✅ | ❌ | ❌ |
+| Sheets への非同期投影 | ✅ | ❌ | ❌ |
+| 耐久性のある書き込みリトライと重複排除 | ✅ | ❌ | ❌ |
+| 競合を考慮したシート更新 | ✅ | ❌ | ❌ |
+| 行・セルの直接操作 | 限定的 | ✅ | ✅ |
+| Google Sheets API へのフルアクセス | Provider 経由 | 一部 | ✅ |
+
+## インストール
+
+```sh
+npm install hikoutei @mikro-orm/core @mikro-orm/sql
+```
+
+ライブラリのインストールだけでは Google Cloud には何も作られません —
+デフォルトはローカル専用(SQLite)で動作します。シート同期が必要なときだけ
+下の setup を実行してください。
+
+## セットアップ(Google Sheets 同期)
+
+一回きりの対話操作です。gcloud CLI をインストールしてから:
+
+```sh
+npx hikoutei setup
+```
+
+Cloud プロジェクト・サービスアカウント・キー・スプレッドシートを作成し、
+`.env` まで書き出します。`HIKOUTEI_SYNC_SPREADSHEET_URL` がなければ
+`createTypedSheets()` はローカル専用(SQLite)のままです。詳細な設定、
+クレデンシャルプール、クォータガイド、手動セットアップ:
+[Google Sheets の設定](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/setup.md)。
+
+## 使い方
 
 スカラーエンティティを定義し、リクエストローカルなマネージャーでローカル
 SQLite の権威を利用します。
@@ -48,6 +96,8 @@ const User = defineTypedSheetsEntity({
   properties: {
     id: { type: "string", primary: true },
     name: { type: "string" },
+    age: { type: "number" },
+    active: { type: "boolean" },
   },
 });
 
@@ -57,231 +107,39 @@ const hikoutei = await createTypedSheets({
 });
 
 const em = hikoutei.em.fork();
-const user = em.create(User, { id: "u1", name: "Ada" });
+const user = em.create(User, { id: "u1", name: "Ada", age: 36, active: true });
 em.persist(user);
 await em.flush();
 
 user.name = "Ada Lovelace";
 await em.flush();
-```
-
-**シートには何が起きるのか?** 書き込みは即座にローカル SQLite へコミット
-されます — アプリケーションのリクエストは Google を待ちません。同期サービスが
-有効な場合、Hikoutei は後でエンティティを登録済みの Google Sheet へバック
-グラウンドで投影します。シート上で行われた人の編集は観察・検証され、SQLite
-へ受け入れられるか競合として記録されるかのどちらかで、決して静かに上書き
-されません。
-
-## Hikoutei を使う理由
-
-- シートの行を手動で変換する代わりに、型付きエンティティを定義する。
-- Google Sheets を待たずにローカル SQLite で読み書きする。
-- コミットされた変更を Sheets へバックグラウンドで同期する。
-- 予期しない列の変更や重複ヘッダーを検出する。
-- 競合時に新しいシート編集を上書きしない。
-
-## Hikoutei が適しているケース
-
-Hikoutei は以下のケースに適しています。
-
-- 製品ワークフローの一部にスプレッドシートがある MVP・プロトタイプ
-- 社内ツールや低トラフィックの管理アプリケーション
-- 人が Sheets を簡単に確認しつつ、型付きのアプリケーションデータを扱いたい
-  チーム
-- SQLite をローカルで使い、非同期のシート更新を受け入れられるサービス
-
-## 他のツールを選ぶべきケース
-
-次の要件がある場合は、通常のデータベースと Google API を直接使ってください。
 
-- 多くの行やサービスにまたがる強いトランザクション
-- 高い書き込みスループットや多数の同時ライター
-- 複雑なクエリ・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 の同期はサービス側の関心事です。アプリケーションは provider
-クライアントを import したり、`createTypedSheets()` にシートルートを渡したり、
-書き込みごとに操作を選んだりしません — ルート API が受け取るのは `dbName` と
-`entities` だけです。同期ランタイムはサービスアカウントを使う単一の内部
-Google Sheets API provider を使用します — Apps Script のデプロイは不要です。
-同期の自動開始は `HIKOUTEI_SYNC_SPREADSHEET_URL` と
-`GOOGLE_APPLICATION_CREDENTIALS` で選択され、設定する公開
-`googleSheetsApi` bootstrap オプションはありません。
-
-### 環境変数による同期の自動開始
-
-スプレッドシートの 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
+const loaded = await em.findOne(User, { id: "u1" });
+if (loaded !== null) {
+  em.remove(loaded);
+  await em.flush();
+}
 ```
 
-```ts
-const hikoutei = await createTypedSheets({ dbName: "./hikoutei.sqlite", entities: [User] });
-```
+読み取り・トランザクション・演算子の詳細:
+[クイックスタート](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/quick-start.md)。
 
-`HIKOUTEI_SYNC_SPREADSHEET_URL` がない場合、`createTypedSheets()` はローカル
-専用 (SQLite) のままです。起動失敗は明確なメッセージで診断されます: URL の
-不正、資格情報ファイルの欠落・不正、スプレッドシートに共有されていない
-サービスアカウント (共有すべきメールアドレスをエラーが教えてくれます)。
-
-### 手動でのサービスアカウント設定
-
-1. **サービスアカウントを作成する。** Cloud プロジェクトで Google Sheets API
-   を有効化し、`https://www.googleapis.com/auth/spreadsheets` スコープの
-   サービスアカウントを作成して、対象スプレッドシートをそのメールアドレスに
-   **編集者(Editor)**として共有します。provider がタブを作成し、効果行と
-   receipt レコードを書き、行アンカーを管理するため、閲覧者権限では不十分
-   です。
-2. **キーはサーバー側に置く。** サービスアカウントのキーパスはサーバーの
-   `GOOGLE_APPLICATION_CREDENTIALS` に、スプレッドシート ID は追跡されない
-   シークレットストアに置きます。キーをブラウザコードや Git に入れないで
-   ください。
-3. **アプリケーションを通常どおり実行する。** `GOOGLE_APPLICATION_CREDENTIALS`
-   と `HIKOUTEI_SYNC_SPREADSHEET_URL` を設定した状態でアプリを起動すると、
-   `createTypedSheets()` がそれを検出して内部 sync bootstrap を開始します —
-   登録済みタブのヘッダーを作成・検証した後、outbox 配信と User_Input
-   ポーリングを開始します。渡す provider オプションも、手動で開始する内部
-   bootstrap もありません。
-
-> **レガシースプレッドシートの注意。** 旧 Apps Script provider が developer
-> metadata の行アンカーでプロビジョニングしたスプレッドシートは移行されませ
-> ん。`User_Input` タブは `__hikoutei_row_id` システム列を必要とするため、
-> レガシータブは再プロビジョニングが必要です。
-
-Hikoutei は、永続的なローカル outbox・冪等な配信・競合を考慮した更新を使う
-ため、一時的な API 障害でコミット済みのアプリケーション書き込みが失われる
-ことはありません。provider は資格情報・スプレッドシート ID・URL・ペイロードを
-ログに残さず、Google の割り当て枠に収まるようリクエスト開始間隔を調整します。
-詳細な状態機械と復旧ルールは[内部整合性モデル](website/guide/internal-consistency.md)を
-参照してください。
-
-ライブの Google 呼び出しはオプトインであり、通常の検証経路はフェイク
-provider と SQLite フィクスチャです。詳細なセットアップとトラブルシューティン
-グは[クイックスタート](website/guide/quick-start.md)を参照してください。
+書き込みは即座にローカル SQLite にコミットされます — リクエストは Google を
+待ちません。シートで人が編集するとポーリングで戻ってきて、SQLite に取り込まれる
+か競合として記録され、黙って上書きされることはありません。パイプライン全体
+(outbox、配信、競合処理)は
+[書き込みと同期フロー](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/sync-flow.md) を参照してください。
 
-## インストール
-
-プロジェクト名と npm パッケージ名はどちらも `hikoutei` です。現在の組み込み
-SQLite provider は MikroORM を必要とします。
-
-```sh
-npm install hikoutei @mikro-orm/core @mikro-orm/sql
-```
-
-MikroORM は実装の詳細であり、Hikoutei の公開エンティティ API には現れません。
-
-## ドキュメント
-
-- [クイックスタート](website/guide/quick-start.md) — インストール、ORM ライフサイクル、
-  サービス側の同期設定
-- [アーキテクチャ](website/guide/architecture.md) — ローカルストアとシートビューの関係
-- [書き込みと同期フロー](website/guide/sync-flow.md) — 非同期配信と
-  復旧動作
-- [内部整合性モデル](website/guide/internal-consistency.md) — 永続的な outbox、
-  冪等な配信、競合を考慮した更新
-- [開発](website/guide/contributing.md) — ローカル開発とテストコマンド
-- [ベンチマークノート](website/guide/benchmarks.md) — 日付付きの測定と
-  その限界
-
-## 制限事項
-
-- Google Sheets には割り当て枠・レイテンシ・API レート制限があります。
-- シートの更新は非同期であり、アプリケーションはローカル状態を読むべきです。
-- SQLite はサービスのローカルのみであり、分散調整レイヤーではありません。
-- スキーマ変更・手動編集・競合更新には、依然としてアプリケーションの運用
-  ポリシーが必要です。
-
-## ローカルクエリ
-
-読み取りは Hikoutei 独自の型付き演算子を使い、常に SQLite で実行されます。
-
-```ts
-const [users, total] = await em.findAndCount(
-  User,
-  {
-    name: { like: "Ada%" },
-    age: { gte: 18, lt: 65 },
-    active: { in: [true] },
-  },
-  {
-    orderBy: { age: "desc", name: "asc" },
-    limit: 20,
-    offset: 0,
-  },
-);
-```
+## さらに読む
 
-`eq`、`ne`、`gt`、`gte`、`lt`、`lte`、`in`、`nin` は、宣言された
-スカラー型で有効な範囲で利用でき、`like` は文字列専用です。
-`{ active: true }` のような等価条件の省略記法も引き続き利用できます。
-`count()` はページネーション前のフィルター総数を返し、`findAndCount()` は
-1 つの SQLite スナップショットからページと総数を読み取ります。明示的な
-並び順には最後のタイブレーカーとして主キーが追加され、`orderBy` のない
-ページネーションは主キーの昇順を使用します。
-
-## プロジェクトステータス
-
-Hikoutei は活発に開発中です。現在の EntityManager は、スカラーエンティティの
-ライフサイクル操作、型付きローカルフィルターと並び順、`limit` / `offset`
-ページネーション、`count()`、スナップショット整合性のある `findAndCount()`、
-コールバック形式の `transactional()` をサポートします。通常の読み取り元は
-常に SQLite であり、Google Sheets ではありません。シート編集の取り込みと
-競合表示はまだ発展途上です。マイナーバージョンのアップグレード前にリリース
-ノートを確認してください。
-
-## ロードマップ
-
-最初の EntityManager 段階である豊富なローカル読み取りは完了しました。残る段階は
-以下の実装順序に従い、日付やリリース番号は約束しません。
-
-1. **ライフサイクル安全な書き込み**
-   - `upsert` と direct/bulk mutation 機能は、エンティティテーブル、
-     canonical state、永続的な Sheet effect outbox を 1 つの SQLite
-     トランザクションで処理する Hikoutei 独自の契約を通じてのみ追加します。
-   - この原子的なライフサイクルを迂回し得る、生の `nativeInsert`、
-     `nativeUpdate`、`nativeDelete`、または SQL パススルー API は約束しません。
-2. **リレーションとロード**
-   - many-to-one、one-to-many、`populate()` 機能を追加します。
-   - 公開前に、リレーションの SQLite マッピング、Sheets プロジェクション
-     表現、スキーマ動作、競合セマンティクスを一体として設計します。
-3. **スキーマ運用**
-   - マイグレーションとスキーマドリフト管理を追加します。
-   - 検証と運用フローを既存のセットアップツールと統合します。
-
-### 同期と運用
-
-以下の作業は EntityManager の各段階と並行して進めます。
-
-- Google Sheets からの意図的なユーザー編集の取り込みを完了する
-- 更新・削除の競合処理と表示を改善する
-
-現在の作業は[オープンな Issues](https://github.com/ManddarinShop/Hikoutei/issues)を
-参照してください。
+- [クイックスタート](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/quick-start.md) — インストール、ORM
+  ライフサイクル、同期セットアップ
+- [アーキテクチャ](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/architecture.md) — ローカルストアとシート
+  画面の連携
+- [書き込みと同期フロー](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/sync-flow.md) — 非同期配信とリカバリ
+- [制限事項](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/limitations.md) — 他のツールを選ぶべきケース
+- [プロジェクトステータスとロードマップ](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/status.md) — 完了済みと次の作業
 
 ## ライセンス
 
-Hikoutei は [MIT ライセンス](LICENSE)で公開されています。
+Hikoutei は [MIT ライセンス](LICENSE) のもとで公開されています。

package/README.ko.md

@@ -2,6 +2,8 @@
 
 <div align="center">
 
+<img src="assets/hikoutei-icon.png" alt="Hikoutei" width="220" />
+
 # Hikoutei
 
 **SQLite로 앱은 빠르게, Google Sheets로 업무 흐름은 눈에 보이게.**
@@ -11,7 +13,7 @@ Google Sheets 기반 MVP를 위한 타입 안전 리포지토리이자 안전한
 사람이 검토하고 가볍게 협업할 수 있도록 Google Sheets에 비동기로 투영됩니다.
 
 <a href="https://www.npmjs.com/package/hikoutei">npm</a> ·
-<a href="website/guide/quick-start.md">빠른 시작</a> ·
+<a href="https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/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)
@@ -32,43 +34,6 @@ Sheets는 검토, 운영, 가벼운 협업을 위한 화면으로 남습니다.
 > Google Sheets를 권위 있는 애플리케이션 데이터베이스로 취급하지 않습니다.
 > SQLite가 진실의 원천이고, Sheets는 사람을 위한 화면입니다.
 
-## 빠른 시작
-
-스칼라 엔티티를 정의하고 요청-로컬 매니저를 통해 로컬 SQLite authority를
-사용합니다.
-
-```ts
-import { createTypedSheets, defineTypedSheetsEntity } from "hikoutei";
-
-const User = defineTypedSheetsEntity({
-  name: "User",
-  tableName: "users",
-  properties: {
-    id: { type: "string", primary: true },
-    name: { type: "string" },
-  },
-});
-
-const hikoutei = await createTypedSheets({
-  dbName: "./hikoutei.sqlite",
-  entities: [User],
-});
-
-const em = hikoutei.em.fork();
-const user = em.create(User, { id: "u1", name: "Ada" });
-em.persist(user);
-await em.flush();
-
-user.name = "Ada Lovelace";
-await em.flush();
-```
-
-**시트에는 무슨 일이 일어날까?** 쓰기는 즉시 로컬 SQLite에 커밋됩니다 —
-애플리케이션 요청은 Google을 기다리지 않습니다. 동기화 서비스가 활성화되면
-Hikoutei는 나중에 엔티티를 등록된 Google Sheet에 백그라운드로 투영합니다.
-시트에서 이루어진 사람의 수정은 관찰되고 검증되어 SQLite로 수용되거나
-충돌로 기록되며, 절대 조용히 덮어쓰이지 않습니다.
-
 ## Hikoutei를 쓰는 이유
 
 - 시트 행을 수동으로 변환하는 대신 타입 지정 엔티티를 정의합니다.
@@ -77,29 +42,6 @@ Hikoutei는 나중에 엔티티를 등록된 Google Sheet에 백그라운드로
 - 예상치 못한 컬럼 변경과 중복 헤더를 감지합니다.
 - 충돌 중에 더 새로운 시트 수정을 덮어쓰지 않습니다.
 
-## Hikoutei를 쓰기 좋은 때
-
-Hikoutei는 다음 상황에 잘 맞습니다.
-
-- 제품 워크플로의 일부로 스프레드시트가 있는 MVP와 프로토타입
-- 내부 도구와 저트래픽 관리 애플리케이션
-- 사람들이 Sheets를 쉽게 확인하면서 타입 지정된 애플리케이션 데이터를
-  유지하려는 팀
-- SQLite를 로컬에서 사용하고 비동기 시트 업데이트를 수용할 수 있는 서비스
-
-## 다른 도구를 선택해야 할 때
-
-다음이 필요하다면 일반 데이터베이스와 Google API를 직접 사용하세요.
-
-- 여러 행이나 서비스에 걸친 강력한 트랜잭션
-- 높은 쓰기 처리량 또는 많은 동시 작성자
-- 복잡한 쿼리, 조인, 리포팅 워크로드
-- 멀티 서버·멀티 리전 조정
-- Google Sheets에서의 즉시 읽기-쓰기 일관성
-- Google Sheets를 애플리케이션의 주 데이터베이스로 사용
-
-## Hikoutei가 당신에게 맞는 추상화인가요?
-
 Hikoutei는 `google-spreadsheet`나 `@googleapis/sheets`를 대체하지 않습니다 —
 한 단계 위에 위치합니다. 원시 스프레드시트 접근만 필요하다면 API 클라이언트를
 직접 사용하세요.
@@ -114,164 +56,83 @@ Hikoutei는 `google-spreadsheet`나 `@googleapis/sheets`를 대체하지 않습
 | 행·셀 직접 조작 | 제한적 | ✅ | ✅ |
 | 전체 Google Sheets API 접근 | Provider 경유 | 부분적 | ✅ |
 
-## Google Sheets 설정
-
-Google Sheets 동기화는 서비스 측 관심사입니다. 애플리케이션은 provider
-클라이언트를 import하거나, Sheet 라우트를 `createTypedSheets()`에 넘기거나,
-쓰기마다 연산을 선택하지 않습니다 — 루트 API는 `dbName`과 `entities`만
-받습니다. 동기화 런타임은 서비스 계정을 사용하는 하나의 내부 Google Sheets
-API provider를 사용합니다 — Apps Script 배포가 없습니다. 동기화 자동 시작은
-`HIKOUTEI_SYNC_SPREADSHEET_URL`과 `GOOGLE_APPLICATION_CREDENTIALS`로
-선택되며, 설정할 공개 `googleSheetsApi` bootstrap 옵션은 없습니다.
-
-### 환경 변수 기반 동기화 자동 시작
-
-스프레드시트 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,
-없거나 잘못된 자격 증명 파일, 스프레드시트에 공유되지 않은 서비스 계정
-(어떤 이메일을 공유해야 하는지 에러가 알려줍니다).
-
-### 수동 서비스 계정 설정
-
-1. **서비스 계정을 만듭니다.** Cloud 프로젝트에서 Google Sheets API를
-   활성화하고, `https://www.googleapis.com/auth/spreadsheets` 스코프의
-   서비스 계정을 만든 뒤 대상 스프레드시트를 해당 이메일에 **편집자(Editor)**로
-   공유합니다. provider가 탭을 만들고, 효과 행과 receipt 기록을 쓰고, 행
-   anchor를 관리하므로 뷰어 권한으로는 부족합니다.
-2. **키를 서버 측에 둡니다.** 서비스 계정 키 경로를 서버의
-   `GOOGLE_APPLICATION_CREDENTIALS`에, 스프레드시트 ID는 추적되지 않는
-   비밀 저장소에 둡니다. 키를 브라우저 코드나 Git에 넣지 마세요.
-3. **애플리케이션을 정상적으로 실행합니다.** `GOOGLE_APPLICATION_CREDENTIALS`와
-   `HIKOUTEI_SYNC_SPREADSHEET_URL`을 설정한 상태로 앱을 시작하면
-   `createTypedSheets()`가 이를 감지해 내부 sync bootstrap을 시작합니다 —
-   등록된 탭의 헤더를 만들고 검증한 뒤 outbox 전달과 User_Input 폴링을
-   시작합니다. 넘길 provider 옵션이나 직접 시작할 내부 bootstrap은 없습니다.
-
-> **레거시 스프레드시트 참고.** 이전 Apps Script provider가 developer
-> metadata 행 anchor로 프로비저닝한 스프레드시트는 마이그레이션되지
-> 않습니다. `User_Input` 탭은 이제 `__hikoutei_row_id` 시스템 컬럼이
-> 필요하므로 레거시 탭을 다시 프로비저닝해야 합니다.
-
-Hikoutei는 내구성 있는 로컬 outbox, 멱등 전달, 충돌을 인지하는 업데이트를
-사용하므로 일시적인 API 실패가 커밋된 애플리케이션 쓰기를 잃게 하지 않습니다.
-provider는 자격 증명, 스프레드시트 ID, URL, 페이로드를 로그에 남기지 않으며,
-Google 할당량 창 안에 머물도록 요청 시작 간격을 조절합니다. 상세 상태 머신과
-복구 규칙은 [내부 정합성 모델](website/guide/internal-consistency.md)을
-참고하세요.
-
-라이브 Google 호출은 opt-in이며, 일반적인 검증 경로는 fake provider와 SQLite
-fixture입니다. 자세한 설정과 문제 해결 단계는 [빠른 시작](website/guide/quick-start.md)을
-참고하세요.
-
 ## 설치
 
-프로젝트와 npm 패키지 이름은 모두 `hikoutei`입니다. 내장 SQLite provider는
-현재 MikroORM을 필요로 합니다.
-
 ```sh
 npm install hikoutei @mikro-orm/core @mikro-orm/sql
 ```
 
-MikroORM은 구현 세부 사항이며 Hikoutei의 공개 엔티티 API에는 나타나지
-않습니다.
+라이브러리 설치만 하면 Google Cloud에는 아무 것도 만들지 않습니다 — 기본은
+로컬 전용(SQLite)으로 동작합니다. 시트 동기화를 원할 때만 아래 setup을
+실행하세요.
 
-## 문서
+## 설정 (Google Sheets 동기화)
 
-- [빠른 시작](website/guide/quick-start.md) — 설치, ORM 생명주기, 서비스 측 동기화 설정
-- [아키텍처](website/guide/architecture.md) — 로컬 저장소와 Sheet 화면이 맞물리는 방식
-- [쓰기 및 동기화 흐름](website/guide/sync-flow.md) — 비동기 전달과
-  복구 동작
-- [내부 정합성 모델](website/guide/internal-consistency.md) — 내구성 outbox,
-  멱등 전달, 충돌을 인지하는 업데이트
-- [개발](website/guide/contributing.md) — 로컬 개발 및 테스트 명령어
-- [벤치마크 노트](website/guide/benchmarks.md) — 날짜가 기록된 측정과
-  그 한계
+1회성 인터랙티브 작업입니다. gcloud CLI 설치 후:
 
-## 한계
+```sh
+npx hikoutei setup
+```
 
-- Google Sheets에는 quota, 지연, API 요청 제한이 있습니다.
-- 시트 업데이트는 비동기이며, 애플리케이션은 로컬 상태를 읽어야 합니다.
-- SQLite는 서비스 로컬 전용이며 분산 조정 계층이 아닙니다.
-- 스키마 변경, 수동 편집, 충돌 업데이트에는 여전히 애플리케이션의 운영 정책이
-  필요합니다.
+Cloud 프로젝트, 서비스 계정, 키, 스프레드시트를 만들고 `.env`까지 써 줍니다.
+`HIKOUTEI_SYNC_SPREADSHEET_URL`이 없으면 `createTypedSheets()`는 로컬 전용
+(SQLite)으로 유지됩니다. 상세 설정, 크리덴셜 풀, 쿼터 가이드, 수동 설정:
+[Google Sheets 설정](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/setup.md).
 
-## 로컬 쿼리
+## 사용법
 
-읽기는 Hikoutei가 정의한 타입 연산자를 사용하며 항상 SQLite에서 실행됩니다.
+스칼라 엔티티를 정의하고 요청-로컬 매니저를 통해 로컬 SQLite authority를
+사용합니다.
 
 ```ts
-const [users, total] = await em.findAndCount(
-  User,
-  {
-    name: { like: "Ada%" },
-    age: { gte: 18, lt: 65 },
-    active: { in: [true] },
-  },
-  {
-    orderBy: { age: "desc", name: "asc" },
-    limit: 20,
-    offset: 0,
-  },
-);
-```
-
-`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`은 선언된 스칼라 타입에
-허용되는 범위에서 사용할 수 있고, `like`는 문자열 전용입니다. `{ active: true }`
-같은 동등 조건 축약도 계속 지원합니다. `count()`는 페이지네이션 전 필터 전체 개수를
-반환하고, `findAndCount()`는 한 SQLite 스냅샷에서 페이지와 전체 개수를 읽습니다.
-명시적 정렬에는 마지막 동률 해소 기준으로 PK가 추가되며, `orderBy` 없는
-페이지네이션은 PK 오름차순을 사용합니다.
+import { createTypedSheets, defineTypedSheetsEntity } from "hikoutei";
 
-## 프로젝트 상태
+const User = defineTypedSheetsEntity({
+  name: "User",
+  tableName: "users",
+  properties: {
+    id: { type: "string", primary: true },
+    name: { type: "string" },
+    age: { type: "number" },
+    active: { type: "boolean" },
+  },
+});
 
-Hikoutei는 활발히 개발 중입니다. 현재 EntityManager는 스칼라 엔티티 생명주기,
-타입 로컬 필터와 정렬, `limit` / `offset` 페이지네이션, `count()`, 스냅샷이
-일관된 `findAndCount()`, 콜백형 `transactional()`을 지원합니다. 일반 읽기는
-Google Sheets가 아니라 항상 SQLite에서 수행됩니다. 시트 편집 수집과 충돌 표시는
-아직 발전 중입니다. 마이너 버전 업그레이드 전에 릴리스 노트를 확인하세요.
+const hikoutei = await createTypedSheets({
+  dbName: "./hikoutei.sqlite",
+  entities: [User],
+});
 
-## 로드맵
+const em = hikoutei.em.fork();
+const user = em.create(User, { id: "u1", name: "Ada", age: 36, active: true });
+em.persist(user);
+await em.flush();
 
-첫 EntityManager 단계인 풍부한 로컬 읽기는 완료됐습니다. 남은 단계는 아래 구현
-순서를 따르며, 일정이나 릴리스 번호는 약속하지 않습니다.
+user.name = "Ada Lovelace";
+await em.flush();
 
-1. **생명주기 안전 쓰기**
-   - `upsert`와 direct/bulk mutation 기능은 엔티티 테이블, canonical state,
-     내구성 있는 Sheet effect outbox를 하나의 SQLite 트랜잭션에서 처리하는
-     Hikoutei 정의 계약을 통해서만 추가합니다.
-   - 이 원자적 생명주기를 우회할 수 있는 원시 `nativeInsert`, `nativeUpdate`,
-     `nativeDelete` 또는 SQL 패스스루 API는 약속하지 않습니다.
-2. **관계와 로딩**
-   - many-to-one, one-to-many, `populate()` 기능을 추가합니다.
-   - 공개 전에 관계의 SQLite 매핑, Sheets 프로젝션 표현, 스키마 동작, 충돌
-     의미론을 함께 설계합니다.
-3. **스키마 운영**
-   - 마이그레이션과 스키마 드리프트 관리를 추가합니다.
-   - 검증 및 운영 흐름을 기존 설정 도구와 통합합니다.
+const loaded = await em.findOne(User, { id: "u1" });
+if (loaded !== null) {
+  em.remove(loaded);
+  await em.flush();
+}
+```
 
-### 동기화 및 운영
+더 많은 읽기·트랜잭션·연산자: [빠른 시작](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/quick-start.md).
 
-다음 작업은 EntityManager 단계와 병행합니다.
+쓰기는 즉시 로컬 SQLite에 커밋됩니다 — 요청은 Google을 기다리지 않습니다.
+시트에서 사람이 편집하면 폴링으로 되돌아와 SQLite에 수용되거나 충돌로
+기록되며, 절대 조용히 덮어쓰이지 않습니다. 전체 파이프라인(outbox, 전달,
+충돌 처리)은 [쓰기 및 동기화 흐름](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/sync-flow.md)을 참고하세요.
 
-- Google Sheets에서 의도적인 사용자 편집 수집 완성
-- 업데이트·삭제 충돌 처리와 표시 개선
+## 더 보기
 
-현재 작업은 [오픈 이슈](https://github.com/ManddarinShop/Hikoutei/issues)를
-참고하세요.
+- [빠른 시작](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/quick-start.md) — 설치, ORM 생명주기, 동기화 설정
+- [아키텍처](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/architecture.md) — 로컬 저장소와 Sheet 화면이 맞물리는 방식
+- [쓰기 및 동기화 흐름](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/sync-flow.md) — 비동기 전달과 복구 동작
+- [한계](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/limitations.md) — 다른 도구를 선택해야 할 때
+- [프로젝트 상태와 로드맵](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/status.md) — 완료된 것과 다음 작업
 
 ## 라이선스
 
-Hikoutei는 [MIT 라이선스](LICENSE)로 배포됩니다.
+Hikoutei는 [MIT 라이선스](LICENSE)로 배포됩니다.

package/README.md

@@ -2,6 +2,8 @@
 
 <div align="center">
 
+<img src="assets/hikoutei-icon.png" alt="Hikoutei" width="220" />
+
 # Hikoutei
 
 **Keep your app fast with SQLite. Keep your workflow visible in Google Sheets.**
@@ -12,7 +14,7 @@ changes are asynchronously projected to Google Sheets for human review and
 lightweight collaboration.
 
 <a href="https://www.npmjs.com/package/hikoutei">npm</a> ·
-<a href="website/guide/quick-start.md">Quick start</a> ·
+<a href="https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/quick-start.md">Quick start</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)
@@ -34,46 +36,6 @@ collaboration.
 > and it does not treat Google Sheets as the authoritative application
 > database. SQLite is the source of truth; Sheets is the human-facing view.
 
-## Quick start
-
-Define a scalar entity and use the local SQLite authority through a
-request-local manager.
-
-```ts
-import { createTypedSheets, defineTypedSheetsEntity } from "hikoutei";
-
-const User = defineTypedSheetsEntity({
-  name: "User",
-  tableName: "users",
-  properties: {
-    id: { type: "string", primary: true },
-    name: { type: "string" },
-    age: { type: "number" },
-    active: { type: "boolean" },
-  },
-});
-
-const hikoutei = await createTypedSheets({
-  dbName: "./hikoutei.sqlite",
-  entities: [User],
-});
-
-const em = hikoutei.em.fork();
-const user = em.create(User, { id: "u1", name: "Ada", age: 36, active: true });
-em.persist(user);
-await em.flush();
-
-user.name = "Ada Lovelace";
-await em.flush();
-```
-
-**What happens to the Sheet?** The write commits to local SQLite immediately —
-the application request never waits on Google. When the sync service is
-enabled, Hikoutei later projects the entity to the registered Google Sheet in
-the background. Human edits made in the sheet are observed, validated, and
-either accepted back into SQLite or recorded as conflicts, never silently
-overwritten.
-
 ## Why Hikoutei?
 
 - Define typed entities instead of manually converting Sheet rows.
@@ -82,29 +44,6 @@ overwritten.
 - Detect unexpected column changes and duplicate headers.
 - Avoid overwriting newer Sheet edits during conflicting updates.
 
-## When to use Hikoutei
-
-Hikoutei is a good fit for:
-
-- MVPs and prototypes where a spreadsheet is part of the product workflow.
-- Internal tools and low-traffic administrative applications.
-- Teams that want typed application data while keeping Sheets easy for people
-  to inspect.
-- Services that can use SQLite locally and accept asynchronous Sheet updates.
-
-## When to choose something else
-
-Use a conventional database and direct Google APIs when you need:
-
-- Strong transactions across many rows or services.
-- High write throughput or many concurrent writers.
-- Complex queries, joins, or reporting workloads.
-- Multi-server or multi-region coordination.
-- Immediate read-after-write consistency in Google Sheets.
-- Google Sheets to be the primary database for the application.
-
-## Is Hikoutei the right abstraction for you?
-
 Hikoutei does not replace `google-spreadsheet` or `@googleapis/sheets` — it
 sits one level above them. If you only need raw spreadsheet access, use the API
 client directly.
@@ -119,289 +58,83 @@ client directly.
 | Direct row and cell manipulation | Limited | ✅ | ✅ |
 | Full Google Sheets API access | Provider only | Partial | ✅ |
 
-## Google Sheets setup
-
-Google Sheets synchronization is a service-side concern. Applications do not
-import a provider client, pass Sheet routes to `createTypedSheets()`, or choose
-an operation for each write — `CreateTypedSheetsOptions` fields (`dbName`,
-`entities`, `providerOptions`) are all optional. The sync runtime uses one
-internal Google Sheets API provider with a service account — no Apps Script
-deployment. Sync auto-start is selected by `HIKOUTEI_SYNC_SPREADSHEET_URL`
-plus `GOOGLE_APPLICATION_CREDENTIALS`. Optional `providerOptions` tunes the
-sync-path provider (telemetry/timeouts; inert when local-only), and
-`createTypedSheetsWithSync()` exposes the same options with a richer result
-for existing-sheet adoption.
-
-**Fastest path:** install the gcloud CLI, then run `npx hikoutei setup` from your
-project directory. On an interactive terminal it offers (press Enter) to
-start `gcloud auth login --enable-gdrive-access --force` for you when the
-active account is missing or lacks Drive access — you only complete the
-browser approval yourself. (In `--yes`, CI, or non-TTY sessions, run that
-login command yourself first.) Setup then creates the project, service
-account, and key, creates a spreadsheet owned by your account, shares it
-with the service account as an Editor, verifies service-account access, and
-writes `GOOGLE_APPLICATION_CREDENTIALS` plus `HIKOUTEI_SYNC_SPREADSHEET_URL`
-into your `.env`. The human access token is used in memory only and never
-stored. Automatic setup runs on macOS and Linux; on Windows a non-dry-run
-is refused before any mutation and manual setup is available. Interrupted runs resume from a local checkpoint
-(`.hikoutei-setup-state.json`); a spreadsheet create whose outcome is
-unknown is reconciled by its creation marker on the next run and setup
-never creates a second spreadsheet (inspect Drive and rerun if setup
-reports `sheet_create_uncertain`, and a create rejected up front with
-HTTP 400/403 plus a confirmed-zero marker lookup rolls back to `key_ready`
-so a corrected rerun starts a fresh marker). Sharing is write-ahead too:
-`spreadsheet_share_started` is persisted before the idempotent SA writer
-permission ensure and `spreadsheet_shared` after it, so a crash between
-the remote permission mutation and the checkpoint write resumes the
-ensure on the next run and never creates a second spreadsheet. The
-service-account key is
-created under a write-ahead contract too: the user-managed key list is
-recorded as a baseline before the single gcloud key create, and
-`key_create_started`/`key_ready` checkpoints let a crashed run recover a
-staged or installed key instead of creating a second one. Only the
-invocation that just persisted `key_create_started` may issue the one key
-create; resumed runs are reconcile-only and, when no credential and no
-post-baseline key are visible, poll the key list plus staged/final
-evidence for up to two minutes (2, 4, 8, 16, 30, 30, 30 s) before failing
-with `key_create_uncertain` — the create is never retried automatically.
-An unmatched user-managed key with no local credential is never deleted
-automatically — setup fails with `key_create_uncertain` and you inspect
-the key list in the Google Cloud console before rerunning (a
-verified-absent state requires removing the setup state file to reset the
-key checkpoint); reused keys are enforced to owner-only mode 600. An exclusive lock directory
-(`.hikoutei-setup-state.json.lock`) prevents concurrent runs and is never
-removed automatically: a crash leaves an empty lock directory behind, and
-removing it manually is required only when you are certain no setup is
-running. Starting fresh requires removing or moving both the checkpoint and
-the key file, or passing `--project` to recover an existing key —
-checkpointed or identity-matched cloud resources are reused, and setup
-never deletes cloud resources. The manual steps below remain available for
-advanced setups.
-
-**Setup progress.** `hikoutei setup` reports step-by-step progress to
-**stderr** across the ten setup phases (cloud auth, Drive access, project,
-APIs, service account, service-account key, spreadsheet, share,
-service-account access, output): an **overall bar** advances only when a
-phase actually completes — it is never an ETA and never guesses a
-percentage — and a **detail line** shows the bounded propagation checks
-(how many of the eight key/access checks have run) and the known 2, 4, 8,
-16, 30, 30, 30 s waits, with a fixed `working…` label for unknown-duration
-steps. On an interactive terminal the four-line block redraws in place;
-in CI, non-TTY, or `NO_COLOR` sessions one static line is printed per
-phase/retry event with no control sequences. Progress pauses and the
-block is cleared during the interactive `gcloud auth login` handoff and
-resumes with the retry. Progress never prints credentials, tokens, keys,
-project ids, emails, paths, or raw command output, and it can never
-change the setup result or exit code; `--dry-run` prints the command
-plan only.
-
-**Keep setup artifacts out of Git.** `hikoutei setup` writes its defaults
-into the current directory: the service-account key
-(`hikoutei-service-account.json`, owner-only mode 600 — a secret), the
-resume checkpoint (`.hikoutei-setup-state.json` and its `.tmp`/unique-temp
-and `.lock` siblings), private key staging/cleanup directories
-(`.hikoutei-key-stage-*`, `.hikoutei-key-cleanup-*`), and
-`.hikoutei-env-*` temporary env writes. The repository's `.gitignore`
-already ignores these defaults, so a plain `git add .` does not pick them
-up. A `.gitignore` is **not a security boundary**, though: it only keeps
-untracked files out of `git add`, and it does not protect files that are
-already tracked (remove a mistakenly tracked key from history and rotate
-it — delete the user-managed key in the Cloud console and rerun setup).
-When you use a custom `--output` or keep the key or checkpoint at custom
-paths, add those exact paths to your application's ignore rules and never
-commit them.
-
-### Env-driven sync auto-start
-
-Set the spreadsheet URL in the environment and `createTypedSheets()` starts
-the Sheets sync internally — `flush()` then flows to Google Sheets through
-the outbox worker with no per-call setup:
+## Installation
 
 ```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] });
+npm install hikoutei @mikro-orm/core @mikro-orm/sql
 ```
 
-Without `HIKOUTEI_SYNC_SPREADSHEET_URL`, `createTypedSheets()` stays
-local-only (SQLite). Startup failures are diagnosed with clear messages:
-invalid URL, missing/invalid credentials file, or a service account not
-shared on the spreadsheet (the error tells you which email to share).
-
-### Manual service-account setup
-
-1. **Create a service account.** Enable the Google Sheets API in a Cloud
-   project, create a service account with the
-   `https://www.googleapis.com/auth/spreadsheets` scope, and share the target
-   spreadsheet with its email as an **Editor**. The provider creates tabs,
-   writes effect rows and receipt records, and manages row anchors, so Viewer
-   access is not enough.
-2. **Keep the key server-side.** Put the service-account key path in
-   `GOOGLE_APPLICATION_CREDENTIALS` on the server and the spreadsheet ID in an
-   untracked secret store. Never put the key in browser code or Git: add the
-   key path (and any custom `.env`/checkpoint paths) to the application's
-   `.gitignore` — the defaults created by `hikoutei setup` are already
-   ignored, but a `.gitignore` is not a security boundary and does not
-   protect already-tracked files.
-3. **Run the application normally.** Start the app with
-   `GOOGLE_APPLICATION_CREDENTIALS` and `HIKOUTEI_SYNC_SPREADSHEET_URL` set;
-   `createTypedSheets()` detects them and starts the internal sync bootstrap —
-   it creates and verifies headers on the registered tabs, then starts outbox
-   delivery and User_Input polling. Pass `providerOptions` only when sync-path
-   tuning is needed; there is no internal bootstrap to start by hand.
-
-> **Legacy spreadsheet note.** Spreadsheets provisioned by the old Apps Script
-> provider with developer-metadata row anchors are not migrated: `User_Input`
-> tabs now require the `__hikoutei_row_id` system column, so legacy tabs must
-> be re-provisioned. Current provisioning also adds one internal formula
-> column, `__hikoutei_row_check`, directly after each `User_Input` tab's
-> registered range: Hikoutei writes a change-detection formula per row, and
-> polling reads only that column to spot human edits (rows without it fall
-> back to full reads). Do not edit, sort, or delete the column or its
-> formulas.
-
-Hikoutei uses a durable local outbox, idempotent delivery, and conflict-aware
-updates so temporary API failures do not lose committed application writes. The
-provider never logs credentials, spreadsheet IDs, URLs, or payloads, and it
-spaces request starts to stay inside Google's quota windows. See the
-[internal consistency model](website/guide/internal-consistency.md) for the
-detailed state machine and recovery rules.
-
-Live Google calls are opt-in; fake providers and SQLite fixtures are the normal
-verification path. The detailed setup and troubleshooting steps are in the
-[Quick start](website/guide/quick-start.md) and [Google Sheets setup](website/guide/setup.md) —
-including the credential pool (`--sa-count`) and API quota guidance when
-polling-heavy workloads hit HTTP 429.
+Installing the library does not touch Google Cloud — it runs local-only
+(SQLite) by default. Run the setup command below only when you want Sheet
+sync.
 
-## Installation
+## Setup (Google Sheets sync)
 
-The project and npm package are both called `hikoutei`. This repo uses pnpm
-(packageManager `pnpm@11.1.2`):
+One-time, interactive. Install the gcloud CLI, then:
 
 ```sh
-pnpm install --frozen-lockfile
+npx hikoutei setup
 ```
 
-`@mikro-orm/core` and `@mikro-orm/sql` are optional peers (`optional: true`),
-lazy-loaded only when a runtime opens. `npm install` still works for consumers.
-
-## Documentation
-
-- [Quick start](website/guide/quick-start.md) — installation, ORM lifecycle,
-  and service-side sync setup.
-- [Architecture](website/guide/architecture.md) — how the local store and
-  Sheet views fit together.
-- [Write and synchronization flow](website/guide/sync-flow.md) —
-  asynchronous delivery and recovery behavior.
-- [Internal consistency model](website/guide/internal-consistency.md) —
-  durable outbox, idempotent delivery, and conflict-aware updates.
-- [Contributing](website/guide/contributing.md) — local development and test
-  commands.
-- [Soak testing](website/guide/soak-testing.md) — the long-duration soak
-  runner: source build, six scalar tables, 6h preflight and 24h direct-live
-  runs, log envs, redaction contract, resume/cleanup, and acceptance
-  criteria.
-- [Benchmark notes](website/guide/benchmarks.md) — dated measurements and
-  their limitations.
-
-## Limitations
-
-- Google Sheets has quota, latency, and API rate limits. The outbound sync
-  worker batches effects to the spreadsheet scope, so remote request volume
-  does not grow with the number of tabs a dispatch touches.
-- Sheet updates are asynchronous; the application should read its local state.
-- SQLite is local to the service and is not a distributed coordination layer.
-- Schema changes, manual edits, and conflicting updates still need an
-  operational policy from the application.
-- The EntityManager is an ORM-style facade over scalar entities, not a full
-  ORM: entity definitions are scalar-only (`string`, `number`, `boolean`,
-  `date`), and v1 permits uniqueness only on the primary/business key.
-- Relations, joins, `populate()`, migrations, cascades, bulk/ORM query
-  builders, and raw SQL are unsupported in this milestone. Sheets is an async
-  projection and human input surface, never a live query database.
-
-## Local queries
-
-Reads use Hikoutei-owned typed operators and always execute against SQLite:
+This creates the Cloud project, service account, key, and spreadsheet, and
+writes `.env` for you. Without `HIKOUTEI_SYNC_SPREADSHEET_URL`,
+`createTypedSheets()` stays local-only (SQLite). Details, credential pools,
+quota guidance, and manual setup: [Google Sheets setup](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/setup.md).
+
+## Usage
+
+Define a scalar entity and use the local SQLite authority through a
+request-local manager.
 
 ```ts
-const [users, total] = await em.findAndCount(
-  User,
-  {
-    name: { like: "Ada%" },
-    age: { gte: 18, lt: 65 },
-    active: { in: [true] },
-  },
-  {
-    orderBy: { age: "desc", name: "asc" },
-    limit: 20,
-    offset: 0,
+import { createTypedSheets, defineTypedSheetsEntity } from "hikoutei";
+
+const User = defineTypedSheetsEntity({
+  name: "User",
+  tableName: "users",
+  properties: {
+    id: { type: "string", primary: true },
+    name: { type: "string" },
+    age: { type: "number" },
+    active: { type: "boolean" },
   },
-);
+});
+
+const hikoutei = await createTypedSheets({
+  dbName: "./hikoutei.sqlite",
+  entities: [User],
+});
+
+const em = hikoutei.em.fork();
+const user = em.create(User, { id: "u1", name: "Ada", age: 36, active: true });
+em.persist(user);
+await em.flush();
+
+user.name = "Ada Lovelace";
+await em.flush();
+
+const loaded = await em.findOne(User, { id: "u1" });
+if (loaded !== null) {
+  em.remove(loaded);
+  await em.flush();
+}
 ```
 
-`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, and `nin` are available where
-valid for the declared scalar type; `like` is string-only. Equality shorthand
-such as `{ active: true }` remains supported. `count()` returns the unpaged
-filter total, and `findAndCount()` returns the filtered page plus a total
-that ignores `limit`/`offset` — both read from one SQLite snapshot. When an
-explicit `orderBy` omits the primary key, Hikoutei appends it in ascending
-order as the final tie-breaker; when the primary key is explicitly ordered,
-its supplied position and direction are preserved. Pagination without
-`orderBy` uses primary-key ascending order.
-
-An `offset` alone (no `limit`) is a valid offset-only read, and an explicit
-`limit: 0` returns an empty page rather than being treated as "no limit".
-`findOne()` returns one entity or `null` and accepts ordering but no paging
-options. Malformed filters, operators, ordering, and paging options fail with
-a stable `HikouteiError`; branch on `error.code` through the exported
-`HIKOUTEI_ERROR_CODES` constants (`HIKOUTEI_ERROR_CODES.INVALID_QUERY` and
-`HIKOUTEI_ERROR_CODES.INVALID_SCALAR_VALUE`, which resolve to the lowercase
-runtime codes `invalid_query` and `invalid_scalar_value`) instead of guessing
-strings or parsing messages.
-
-## Project status
-
-Hikoutei is in active development. The current EntityManager supports scalar
-entity lifecycle operations, typed local filters and ordering, `limit` /
-`offset` pagination, `count()`, snapshot-consistent `findAndCount()`, and
-callback-style `transactional()` work. Normal reads always come from SQLite,
-never Google Sheets. Sheet edit ingestion and conflict presentation are still
-evolving. Review release notes before upgrading minor versions.
-
-## Roadmap
-
-The first EntityManager milestone, rich local reads, is complete. Remaining
-milestones follow the implementation order below; no milestone is tied to a
-date or release number.
-
-1. **Lifecycle-safe writes**
-   - Add `upsert` and direct/bulk mutation capabilities only through a
-     Hikoutei-owned contract that preserves one SQLite transaction across the
-     entity table, canonical state, and durable Sheet effect outbox.
-   - Do not promise raw `nativeInsert`, `nativeUpdate`, `nativeDelete`, or SQL
-     pass-through APIs that could bypass that atomic lifecycle.
-2. **Relationships and loading**
-   - Add many-to-one, one-to-many, and `populate()` capabilities.
-   - Design SQLite relationship mapping, Sheets projection representation,
-     schema behavior, and conflict semantics together before public release.
-3. **Schema operations**
-   - Add migration and schema drift management.
-   - Integrate validation and operational workflows with the existing setup
-     tooling.
-
-### Synchronization and operations
-
-The following work continues in parallel with the EntityManager milestones:
-
-- Complete ingestion of intentional user edits from Google Sheets.
-- Improve update/delete conflict handling and presentation.
-
-See the [open issues](https://github.com/ManddarinShop/Hikoutei/issues)
-for current work.
+More reads, transactions, and operators: [Quick start](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/quick-start.md).
+
+Writes commit to local SQLite immediately — the request never waits on Google.
+Human edits in the Sheet flow back through polling — accepted into SQLite or
+recorded as conflicts, never silently overwritten. The full pipeline (outbox,
+delivery, conflict handling) is covered in
+[Write and synchronization flow](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/sync-flow.md).
+
+## Learn more
+
+- [Quick start](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/quick-start.md) — installation, ORM lifecycle, sync setup.
+- [Architecture](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/architecture.md) — local store and Sheet views.
+- [Write and synchronization flow](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/sync-flow.md) — delivery and recovery.
+- [Limitations](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/limitations.md) — when to choose something else.
+- [Project status and roadmap](https://github.com/ManddarinShop/Hikoutei-Website-/blob/main/guide/status.md) — what is done and next.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hikoutei",
-  "version": "0.10.18-dev",
+  "version": "0.10.20-dev",
   "description": "Typed repository and safe write layer for Google Sheets-backed MVPs. SQLite-authoritative entity lifecycle with asynchronous Google Sheets projection.",
   "repository": {
     "type": "git",