From 931384d6714b50f833036edb6cb284d5bf652093 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=9E=97=20=E9=A7=BF=E7=94=AB=20=28Shunsuke=20Hayashi=29?=
 <supernovasyun@gmail.com>
Date: Wed, 15 Apr 2026 09:06:30 +0900
Subject: [PATCH] docs: clarify prerequisites, known limitations, and roadmap
 for v0.1.0

Added explicit prerequisites section to README and quickstart,
known limitations table with planned versions, and v0.2/v0.3/v0.4
roadmap. CHANGELOG restructured with Keep a Changelog format.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CHANGELOG.md       |  95 ++++++++++++++++++++++------
 README.md          | 154 ++++++++++++++++++++++++++++++++++-----------
 docs/quickstart.md | 125 ++++++++++++++++++++++--------------
 3 files changed, 274 insertions(+), 100 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c5daf79..0f63b13 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,30 +1,89 @@
 # GARC Changelog
 
-## [0.1.0] — 2026-04-15
+All notable changes to this project are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [0.1.0] — 2026-04-15 — Initial Release
+
+This is the first public release of GARC. Core operations for Gmail, Calendar,
+Drive, Sheets, Tasks, and People are functional end-to-end. Several enterprise
+features are deferred to v0.2 (see Known Limitations in README).
 
 ### Added
 
-- `bin/garc` — Main CLI entrypoint with full command dispatch
-- `lib/bootstrap.sh` — Disclosure chain loading from Google Drive (SOUL/USER/MEMORY/RULES/HEARTBEAT)
-- `lib/auth.sh` — OAuth scope inference and authorization flow
-- `lib/memory.sh` — Google Sheets memory sync (pull/push/search)
-- `lib/send.sh` — Gmail and Google Chat message sending
-- `lib/agent.sh` — Agent registry via Google Sheets
-- `lib/task.sh` — Google Tasks operations (list/create/done)
-- `lib/approve.sh` — Execution gate and approval flow
+**CLI entrypoint**
+- `bin/garc` — Main CLI with full command dispatch (gmail / calendar / drive / sheets / task / people / memory / ingress / daemon / agent / approve / auth / bootstrap / setup / status / heartbeat)
+
+**Google Workspace operations**
+- `lib/gmail.sh` + `scripts/garc-gmail-helper.py` — send / reply / search / read / inbox / draft / labels / profile
+- `lib/calendar.sh` + `scripts/garc-calendar-helper.py` — today / week / list / create / delete / freebusy
+- `lib/drive.sh` + `scripts/garc-drive-helper.py` — list / search / upload / download / create-doc / share / info
+- `lib/sheets.sh` + `scripts/garc-sheets-helper.py` — info / read / append / update / search / clear
+- `lib/task.sh` + `scripts/garc-tasks-helper.py` — list / create / done / show / update / delete / clear-completed / tasklists
+- `lib/people.sh` + `scripts/garc-people-helper.py` — lookup / directory / list / contacts
+
+**Agent runtime**
+- `lib/bootstrap.sh` — Disclosure chain loading from Google Drive (SOUL.md → USER.md → MEMORY.md → RULES.md → HEARTBEAT.md)
+- `lib/memory.sh` — Google Sheets memory sync (pull / push / search)
+- `lib/agent.sh` — Agent registry via Google Sheets (list / register / show)
+- `lib/approve.sh` — Execution gate and approval flow (gate / list / act / create)
 - `lib/heartbeat.sh` — System state logging to Google Sheets
+- `lib/ingress.sh` — Queue/ingress system with JSONL local cache (enqueue / list / run-once / done / fail / stats)
+- `lib/daemon.sh` — Gmail polling daemon with macOS launchd support (start / stop / status / poll-once / install)
 - `lib/kg.sh` — Knowledge graph via Google Drive Docs
-- `lib/ingress.sh` — Queue/ingress system with JSONL local cache
+
+**Auth & config**
 - `scripts/garc-auth-helper.py` — OAuth2 scope inference + token management
-- `scripts/garc-sheets-helper.py` — Google Sheets CRUD operations
-- `scripts/garc-drive-helper.py` — Google Drive file operations + KG builder
-- `scripts/garc-gmail-helper.py` — Gmail send operations
-- `scripts/garc-tasks-helper.py` — Google Tasks operations
-- `scripts/setup-workspace.sh` — One-shot workspace provisioning
-- `config/scope-map.json` — 25 task types × Google OAuth scopes × 4 profiles
-- `config/gate-policy.json` — Execution gate policies (none/preview/approval)
+- `scripts/garc-core.py` — Shared auth, retry, and utilities
+- `scripts/garc-setup.py` — One-shot workspace provisioner (garc setup all)
+- `config/scope-map.json` — 42 task types × Google OAuth scopes × keyword patterns
+- `config/gate-policy.json` — Execution gate policies (none / preview / approval)
 - `config/config.env.example` — Configuration template
-- `agents.yaml` — Default agent declarations (main/crm-agent/doc-agent/expense-processor)
+- `agents.yaml` — Default agent declarations (main / crm-agent / doc-agent / expense-processor)
+
+**Claude Code bridge**
+- `scripts/garc-ingress-helper.py` — Task type inference + Claude Code execution prompt builder
+- `.claude/skills/garc-runtime/SKILL.md` — Claude Code skill definition
+
+**Documentation**
+- `README.md` — Quickstart, usage, prerequisites, known limitations, roadmap
+- `README.ja.md` — Japanese translation
+- `docs/quickstart.md` — 15-minute setup guide
+- `docs/google-cloud-setup.md` — Google Cloud Console step-by-step
 - `docs/garc-architecture.md` — Full architecture reference
 - `docs/garc-vs-larc.md` — GARC vs LARC comparison
 - `docs/gws-api-alignment.md` — GWS API command mappings
+
+### Known Limitations (v0.1.0)
+
+- Google Chat integration not implemented — Gmail used as fallback for notifications
+- Service Account / Domain-wide Delegation not supported — user OAuth only
+- No audit log
+- `garc auth revoke` not implemented
+- Editing existing Google Docs body not implemented
+- Google Forms → auto-enqueue pipeline not implemented
+- macOS only for daemon install (launchd); Linux systemd not yet supported
+- Single Google Workspace organization only
+
+---
+
+## Unreleased
+
+### v0.2 — Enterprise hardening (planned)
+- Google Chat API (`garc chat send`)
+- Service Account + Domain-wide Delegation (`garc auth login --service-account`)
+- Audit log (`garc audit log`)
+- `garc auth revoke`
+
+### v0.3 — Workflow expansion (planned)
+- Google Docs body editing
+- Google Forms → ingress pipeline
+- Linux systemd daemon support
+- GCP Secret Manager integration
+
+### v0.4 — Multi-agent (planned)
+- Cross-agent task delegation
+- Agent-to-agent approval chains
+- Multi-organization support
diff --git a/README.md b/README.md
index 6d29361..efe6926 100644
--- a/README.md
+++ b/README.md
@@ -12,16 +12,59 @@ You / Claude Code
 Google Workspace APIs (Gmail · Calendar · Drive · Sheets · Tasks · People)
 ```
 
-## Core concepts
+> **This is an initial release (v0.1.0).** Core operations work end-to-end.
+> Known limitations and planned improvements are listed in [Known Limitations](#known-limitations) below.
 
-| Concept | What it does |
-|---------|-------------|
-| **`auth suggest`** | Infers minimum OAuth scopes from a natural-language task description |
-| **Execution gates** | `none` (read-only) / `preview` (writes, confirm first) / `approval` (financial/irreversible, requires human sign-off) |
-| **Disclosure chain** | `SOUL.md → USER.md → MEMORY.md → RULES.md → HEARTBEAT.md` stored in Google Drive, loaded on bootstrap |
-| **Queue / ingress** | Task lifecycle (`pending → in_progress → done/failed`), Gmail polling daemon auto-enqueues new emails |
-| **Agent registry** | Agent declarations (id, model, scopes) stored in Google Sheets |
-| **Memory sync** | Long-term memory round-trip with a dedicated Google Sheets tab |
+---
+
+## Prerequisites
+
+> **Complete all steps below before running any `garc` command.**
+> Skipping any step will result in authentication or API errors.
+
+### 1. Google Account
+
+A Google account with **Gmail, Drive, Sheets, Calendar, and Tasks** active.
+- Personal Gmail accounts work for development and testing.
+- Google Workspace (business) accounts work and are the primary target use case.
+
+### 2. Python 3.10+
+
+```bash
+python3 --version   # must be 3.10 or higher
+```
+
+### 3. Google Cloud Project with APIs enabled
+
+You need a Google Cloud project with the following APIs enabled:
+
+| API | Service name | Used for |
+|-----|-------------|----------|
+| Google Drive API | `drive.googleapis.com` | File storage, disclosure chain |
+| Google Sheets API | `sheets.googleapis.com` | Memory, queue, agent registry |
+| Gmail API | `gmail.googleapis.com` | Email send/receive/search |
+| Google Calendar API | `calendar-json.googleapis.com` | Event management |
+| Google Tasks API | `tasks.googleapis.com` | Task management |
+| Google Docs API | `docs.googleapis.com` | Document creation |
+| Google People API | `people.googleapis.com` | Contacts, directory search |
+
+Step-by-step setup: [`docs/google-cloud-setup.md`](docs/google-cloud-setup.md)
+
+### 4. OAuth 2.0 Credentials file
+
+1. In [Google Cloud Console](https://console.cloud.google.com/) → **Credentials** → **Create OAuth 2.0 Client ID**
+2. Application type: **Desktop app**
+3. Download JSON → save as **`~/.garc/credentials.json`**
+
+```bash
+mkdir -p ~/.garc
+mv ~/Downloads/client_secret_*.json ~/.garc/credentials.json
+```
+
+> Without `~/.garc/credentials.json`, all `garc` commands will fail with
+> `FileNotFoundError: credentials.json not found`.
+
+---
 
 ## Quickstart
 
@@ -36,49 +79,34 @@ source ~/.zshrc
 garc --version   # → garc 0.1.0
 ```
 
-### 2. Enable Google Cloud APIs
-
-In [Google Cloud Console](https://console.cloud.google.com/), enable:
-
-| API | Service name |
-|-----|-------------|
-| Google Drive API | `drive.googleapis.com` |
-| Google Sheets API | `sheets.googleapis.com` |
-| Gmail API | `gmail.googleapis.com` |
-| Google Calendar API | `calendar-json.googleapis.com` |
-| Google Tasks API | `tasks.googleapis.com` |
-| Google Docs API | `docs.googleapis.com` |
-| Google People API | `people.googleapis.com` |
-
-Create an **OAuth 2.0 Client ID** (Desktop app) → download JSON → save as `~/.garc/credentials.json`.
-
-See [`docs/google-cloud-setup.md`](docs/google-cloud-setup.md) for step-by-step instructions.
-
-### 3. Authenticate
+### 2. Authenticate
 
 ```bash
 garc auth login --profile backoffice_agent
 # Opens browser → Google login → authorize all scopes
+# Writes ~/.garc/token.json
 garc auth status
 ```
 
-### 4. Provision workspace
+### 3. Provision workspace
 
 ```bash
 garc setup all
 # Creates GARC Workspace folder in Google Drive
-# Creates Google Sheets with all tabs (memory/agents/queue/heartbeat/approval/…)
-# Uploads disclosure chain templates to Drive
-# Writes IDs to ~/.garc/config.env
+# Creates Google Sheets with all tabs (memory/agents/queue/heartbeat/approval)
+# Uploads disclosure chain templates (SOUL.md / USER.md / MEMORY.md / RULES.md)
+# Writes folder/sheet IDs to ~/.garc/config.env
 ```
 
-### 5. Verify
+### 4. Verify
 
 ```bash
 garc status
 garc bootstrap --agent main
 ```
 
+---
+
 ## Usage
 
 ### Gmail
@@ -88,6 +116,7 @@ garc gmail inbox --unread
 garc gmail search "from:alice@co.com subject:invoice" --max 10
 garc gmail send --to boss@co.com --subject "Weekly report" --body "..."
 garc gmail read <message_id>
+garc gmail draft --to boss@co.com --subject "Draft" --body "..."
 ```
 
 ### Google Calendar
@@ -124,10 +153,19 @@ garc sheets append --sheet memory --values '["main","2026-04-20","key decision",
 ```bash
 garc task list
 garc task create "Write Q1 report" --due 2026-04-30
+garc task done <task_id>
 garc people lookup "Alice Smith"
 garc people directory "engineering"
 ```
 
+### Memory sync
+
+```bash
+garc memory pull              # Download from Google Sheets
+garc memory push "note text"  # Append to memory tab
+garc memory search "keyword"
+```
+
 ### Queue / Ingress (Claude Code bridge)
 
 ```bash
@@ -164,13 +202,15 @@ garc approve list
 garc approve act <id> --action approve
 ```
 
+---
+
 ## Architecture
 
 ```
 ~/.garc/
-  credentials.json      # OAuth client credentials (Google Cloud Console)
-  token.json            # OAuth user token (garc auth login)
-  config.env            # GARC_DRIVE_FOLDER_ID, GARC_SHEETS_ID, …
+  credentials.json      # OAuth client credentials (Google Cloud Console) ← YOU PROVIDE THIS
+  token.json            # OAuth user token (garc auth login generates this)
+  config.env            # GARC_DRIVE_FOLDER_ID, GARC_SHEETS_ID, … (garc setup all generates this)
   cache/
     workspace/<agent>/
       SOUL.md / USER.md / MEMORY.md / RULES.md / HEARTBEAT.md
@@ -188,6 +228,46 @@ garc approve act <id> --action approve
 | `preview` | Medium — external writes | Show plan, confirm first |
 | `approval` | High — financial / irreversible | Create approval request, block until approved |
 
+---
+
+## Known Limitations
+
+The following are known gaps in v0.1.0. They are planned for future releases.
+
+| Limitation | Impact | Planned |
+|-----------|--------|---------|
+| **Google Chat not implemented** | No push notifications to Chat spaces. Gmail is used as fallback for approval notifications | v0.2 |
+| **Service Account / Domain-wide Delegation not supported** | Enterprise deployments requiring headless bot identity (not user OAuth) are not yet supported | v0.2 |
+| **No audit log** | Operations are not logged to Admin SDK / Google Cloud Logging | v0.2 |
+| **`garc auth revoke` not implemented** | Token revocation requires manual deletion of `~/.garc/token.json` | v0.2 |
+| **Existing Google Docs editing limited** | `drive create-doc` creates new docs; editing body of existing Docs is not implemented | v0.3 |
+| **Google Forms → auto-enqueue not implemented** | Form submissions cannot automatically create queue tasks | v0.3 |
+| **Single organization only** | Multi-tenant (multiple Google Workspace domains) is not supported | v0.3+ |
+| **macOS only (daemon)** | `daemon install` generates a macOS launchd plist. Linux systemd not yet supported | v0.3 |
+
+---
+
+## Roadmap
+
+### v0.2 — Enterprise hardening
+- Google Chat API integration (`garc chat send`)
+- Service Account support (`garc auth login --service-account`)
+- Audit log (`garc audit log`)
+- `garc auth revoke`
+
+### v0.3 — Workflow expansion
+- Google Docs body editing
+- Google Forms → ingress pipeline
+- Linux systemd daemon support
+- GCP Secret Manager for credentials
+
+### v0.4 — Multi-agent
+- Cross-agent task delegation
+- Agent-to-agent approval chains
+- Multi-organization support
+
+---
+
 ## Repository layout
 
 ```
@@ -214,6 +294,8 @@ docs/
 .claude/skills/garc-runtime/SKILL.md   Claude Code skill
 ```
 
+---
+
 ## Relation to LARC
 
 GARC mirrors [LARC](https://github.com/miyabi-lab/larc-openclaw-coding-agent) — the same governance model running on Google Workspace instead of Lark/Feishu.
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 5633f92..8b3e8ff 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -1,10 +1,45 @@
 # GARC Quickstart — 15分で動かす
 
-## 前提
+## このドキュメントについて
 
-- Python 3.10+
-- pip3
-- Google アカウント（Gmail / Drive 使用中）
+このガイドは GARC v0.1.0 の初期リリース向けです。
+**以下の前提条件を全て満たしてから**進めてください。途中でスキップすると認証エラーになります。
+
+---
+
+## 前提条件チェックリスト
+
+すべてに ✅ が付いてから先に進んでください。
+
+- [ ] Python 3.10 以上がインストールされている (`python3 --version`)
+- [ ] Google アカウントを持っている（Gmail / Drive が使える状態）
+- [ ] Google Cloud Console でプロジェクトを作成済み
+- [ ] 下記7つのAPIを有効化済み（[詳細手順](google-cloud-setup.md)）
+- [ ] OAuth 2.0 クライアント ID を作成し `~/.garc/credentials.json` に保存済み
+
+### 必須 API（7種）
+
+| API | サービス名 |
+|-----|---------|
+| Google Drive API | `drive.googleapis.com` |
+| Google Sheets API | `sheets.googleapis.com` |
+| Gmail API | `gmail.googleapis.com` |
+| Google Calendar API | `calendar-json.googleapis.com` |
+| Google Tasks API | `tasks.googleapis.com` |
+| Google Docs API | `docs.googleapis.com` |
+| Google People API | `people.googleapis.com` |
+
+> **APIを有効化しないと** `googleapiclient.errors.HttpError: 403 API not enabled` が出ます。
+> 有効化の詳細手順: [google-cloud-setup.md](google-cloud-setup.md)
+
+### credentials.json の配置
+
+```bash
+mkdir -p ~/.garc
+# Google Cloud Console からダウンロードした JSON を配置
+mv ~/Downloads/client_secret_*.json ~/.garc/credentials.json
+ls ~/.garc/credentials.json   # ← このファイルがないと全コマンドが失敗します
+```
 
 ---
 
@@ -28,56 +63,42 @@ garc --version
 
 ---
 
-## Step 2 — Google Cloud Console でAPIを有効化
-
-1. https://console.cloud.google.com/ にアクセス
-2. 新規プロジェクトを作成（または既存を選択）
-3. **「APIとサービス」→「APIとサービスを有効化」** で以下を有効化：
-
-| API | サービス名 |
-|-----|---------|
-| Google Drive API | `drive.googleapis.com` |
-| Google Sheets API | `sheets.googleapis.com` |
-| Gmail API | `gmail.googleapis.com` |
-| Google Calendar API | `calendar-json.googleapis.com` |
-| Google Tasks API | `tasks.googleapis.com` |
-| Google Docs API | `docs.googleapis.com` |
-| Google People API | `people.googleapis.com` |
-
-4. **「認証情報」→「OAuth 2.0 クライアントID」** を作成
-   - アプリタイプ: **デスクトップアプリ**
-   - JSONダウンロード → `~/.garc/credentials.json` に保存
-
-5. **「OAuth同意画面」** → テストユーザーに自分のGmailを追加
-
----
-
-## Step 3 — 認証
+## Step 2 — 認証
 
 ```bash
 garc auth login --profile backoffice_agent
 # → ブラウザが開く → Googleログイン → 全スコープを承認
-# → ~/.garc/token.json が生成される
+# → ~/.garc/token.json が生成される（以降は自動更新）
 
 garc auth status
-# → 付与されたスコープが表示される
+# → 付与されたスコープ一覧が表示される
 ```
 
+> **よくあるエラー**
+> - `credentials.json not found` → Step 0 の前提条件に戻ってください
+> - `Access blocked: This app's request is invalid` → OAuth同意画面でテストユーザーに自分のGmailを追加してください
+
 ---
 
-## Step 4 — ワークスペースを自動プロビジョニング
+## Step 3 — ワークスペースを自動プロビジョニング
 
 ```bash
 garc setup all
-# → Google DriveにGARC Workspaceフォルダを作成
-# → Google Sheetsにすべてのタブを作成（memory/agents/queue/heartbeat/approval...）
-# → 開示チェーンテンプレート（SOUL.md等）をDriveにアップロード
-# → ~/.garc/config.env にIDを自動保存
 ```
 
+このコマンドが実行すること:
+
+| 処理 | 結果 |
+|------|------|
+| Google Drive に `GARC Workspace` フォルダ作成 | `~/.garc/config.env` に `GARC_DRIVE_FOLDER_ID` が書き込まれる |
+| Google Sheets に全タブ作成 | memory / agents / queue / heartbeat / approval タブが作成される |
+| 開示チェーンテンプレートをアップロード | SOUL.md / USER.md / MEMORY.md / RULES.md / HEARTBEAT.md が Drive に配置される |
+
+> **所要時間**: 初回は Google API のプロビジョニングで 1〜2 分かかります。
+
 ---
 
-## Step 5 — 動作確認
+## Step 4 — 動作確認
 
 ```bash
 garc status
@@ -85,10 +106,10 @@ garc status
 
 garc bootstrap --agent main
 # → DriveからSOUL.md/USER.md/MEMORY.md等を読み込み
-# → ~/.garc/cache/workspace/main/AGENT_CONTEXT.md に統合
+# → ~/.garc/cache/workspace/main/AGENT_CONTEXT.md に統合コンテキストを出力
 
 garc auth suggest "send weekly report to manager"
-# → スコープ推定が動く
+# → gate: preview   scopes: gmail.send
 ```
 
 ---
@@ -155,10 +176,22 @@ GARC_DEFAULT_AGENT=main
 
 ## トラブルシューティング
 
-| エラー | 対処 |
-|--------|------|
-| `credentials.json not found` | Google Cloud ConsoleでOAuth認証情報をダウンロード |
-| `Token refresh failed` | `garc auth login` で再認証 |
-| `API not enabled` | Google Cloud ConsoleでAPIを有効化 |
-| `403 insufficientPermissions` | `garc auth login --profile backoffice_agent` で再認証（スコープ追加） |
-| `Sheets tab missing` | `garc setup sheets` でタブを再作成 |
+| エラー | 原因 | 対処 |
+|--------|------|------|
+| `credentials.json not found` | 認証情報ファイルが未配置 | Google Cloud ConsoleでOAuth認証情報をダウンロードし `~/.garc/credentials.json` に保存 |
+| `Token refresh failed` | トークン期限切れ | `garc auth login` で再認証 |
+| `403 API not enabled` | APIが有効化されていない | Google Cloud ConsoleでAPIを有効化（[手順](google-cloud-setup.md)） |
+| `403 insufficientPermissions` | スコープが不足 | `garc auth login --profile backoffice_agent` で再認証（全スコープを付与） |
+| `Sheets tab missing` | Sheetsが未作成 | `garc setup sheets` でタブを再作成 |
+| `Access blocked` | テストユーザー未登録 | OAuth同意画面でテストユーザーにGmailを追加 |
+
+---
+
+## v0.1.0 の既知制限
+
+このリリースで未実装の機能です。詳細は [README の Known Limitations](../README.md#known-limitations) を参照してください。
+
+- Google Chat 通知 → Gmail で代替
+- Service Account（ヘッドレス・ボット用途）→ v0.2 で対応予定
+- 監査ログ → v0.2 で対応予定
+- `garc auth revoke` → 手動で `~/.garc/token.json` を削除してください