diff --git a/README.md b/README.md
index d9bd117..d133375 100644
--- a/README.md
+++ b/README.md
@@ -1,49 +1,117 @@
-
-
-# drive-cli
-
-`drive` imports selected Google Drive folders into local Markdown snapshots and searchable
-documents. It reads Google Docs across all tabs, keeps source identity through renames and moves,
-and reuses WireCat's shared keyword search and optional local embeddings. Shared tags, notes,
-editor identities and evidence-backed memories stay attached to the imported documents.
+
+
+
+ Your agent edits a Google Doc a few lines at a time, from a Markdown file on your computer, while your colleagues + keep writing and commenting in it. For you and for Claude Code, Codex or any app that speaks MCP. +
+ ++ Docs · + Examples · + Discord +
+ + + +- **Edit a Google Doc block by block.** You or your agent change a local Markdown file with any editor or the agent's + usual file edit. `drive personal mirrors sync` sends only the changed blocks, such as a paragraph or a list item, to the Doc. + Comments on the text you left alone stay where they are. +- **Your colleagues' edits are kept.** What they changed in other parts of the Doc comes back into your file. A part + changed on both sides is reported with both versions, never silently written over. +- **Search your Drive with sources.** Import the folders you choose, then search them on your computer by words or by + meaning. Every result links to the original Google file. + +## What you get + +- **An agent that edits like a careful colleague.** It changes the two lines you asked about. The rest of the Doc, and + the comments on it, stay as they were. +- **Changes from Google land in your file.** A colleague's edit comes back on the lines it touched. Your own `*` + bullets and code fences stay as you wrote them. +- **Conflicts you can see.** When the same paragraph changed in the file and in Google, sync shows both versions, who + changed it in Google and when. You choose with `--keep local`, `--keep google` or `--keep both`. +- **Hands-free sync.** `drive personal mirrors watch` syncs on each save and asks Google for changes every minute. +- **Answers with their source.** "What did we decide about the Q4 budget?" returns the passage and the link to the + Doc it came from. + +```text +You: In plans/q4.md, rewrite the Risks section around the vendor delay. Leave the rest. +Agent: (edits 3 lines under "## Risks" in plans/q4.md) + (runs drive personal mirrors sync: 1 file sent, 1 pulled) + The Risks section is updated in the Google Doc. Dana Example changed the Timeline in Google + meanwhile, so her edit is now in your file too. +``` -Drive uses Google's official Node clients. -Sources supported now: native Google Docs and Sheets, PDF, docx, xlsx, CSV, TSV, and uploaded Markdown/TXT. -Other types and shortcuts are reported as skipped; shortcuts are not followed outside the selected scope. +## Why drive + +- **Small edits instead of a new copy.** Google lets programs change a Markdown file in Drive only by replacing all of + it ([measured](https://github.com/WireCatLabs/cli-testing/tree/main/performance/documents/native-markdown)). A + replace writes the agent's copy over the whole file, so an edit a colleague made after the agent read it is lost. + drive keeps a real Google Doc in step with your file and sends small edits next to theirs. Google refuses an edit + from drive if the Doc changed after drive read it, so nothing is written over. +- **What your agent gets that a plain Drive connector does not give.** Claude's built-in Google Drive connector can + create a new file and change a file's title or folder, but not its text (its `update_file` tool, checked + on 2026-11-17). With drive, the agent edits the text itself. +- **Search that stays on your computer.** Google Docs are read across all their tabs, and a document keeps its identity + through renames and moves. Keyword search and optional local embeddings come from WireCat's shared search. +- **Safe to give to an agent.** Reads are the default. Changes in Google need a sign-in with `--grant write`, and + `DRIVE_READ_ONLY=1` refuses every change. +- **Free and open source.** Apache 2.0, built on Google's official Node clients. How it compares with gog, Workspace MCP and rclone, and when another tool fits better: [compared with other tools](docs/compare.md). -## Install - -Install the compiled CLI with Node 22.16+ on the 22.x line or Node 24+. A source build is not -required: +## Quick start ```sh npm install -g @wirecat/drive-cli -drive --version -drive --help +drive personal session start --grant write +drive personal mirrors add ./notes --parent https://drive.google.com/drive/folders/FOLDER_ID +drive personal mirrors sync ``` -See [installation and Google connection](docs/installation.md). Source builds are for -[contributors](docs/dev/DEVELOPMENT.md). +`personal` is a name you choose for this Google account. The first sync turns each `.md` file in `./notes` into a +Google Doc in that folder. Edit a file, run `mirrors sync` again, and only what changed reaches the Doc. The full +guide, with CSV files as Sheets and what happens on a conflict: [mirror local files with Google](docs/mirrors.md). + +You need Node 22.16+ on the 22.x line or Node 24+. See [installation and Google connection](docs/installation.md). +Source builds are for [contributors](docs/dev/DEVELOPMENT.md). `drive doctor` shows the version, settings file, profiles and paths without signing in, and `drive upgrade` installs a newer version with the package manager that installed drive. -`drive guide` lists scenarios — the commands for a common task, in order — and `drive commands --json` is the full -command tree. For an agent, `drive skill install` puts drive's instructions where Claude Code, Codex, Gemini CLI and -OpenClaw look (Hermes with `--for hermes`), `drive personal mcp serve` serves three MCP tools (search, read, write) — -`--http` serves them to ChatGPT and Claude in the browser ([remote MCP](docs/remote.md)) — and `DRIVE_READ_ONLY=1` -refuses every change, as `--read-only` does. +## Use it with your agent + +Ask in plain words. The agent picks the commands. + +> *"Use drive. Tighten the intro of notes/launch.md and sync it to the Doc."* +> *"Use drive. Find what we decided about the vendor contract, with the link."* + +- **Claude Code, Codex** and other agents with a terminal edit the Markdown file with their usual file tools and run + `drive` themselves. `drive skill install` puts drive's instructions where Claude Code, Codex, Gemini CLI and + OpenClaw look (Hermes with `--for hermes`). +- **Apps that speak MCP** connect to `drive personal mcp serve`. It serves three tools (search, read, write), and + an agent can run `mirrors sync` through them. `mirrors watch` runs only from the command line. +- **ChatGPT and Claude in the browser** reach it with `--http` ([remote MCP](docs/remote.md)). + +`drive guide` lists scenarios, the commands for a common task in order, and `drive commands --json` is the full +command tree. `DRIVE_READ_ONLY=1` refuses every change, as `--read-only` does. ## Sign in and choose folders Sign in with WireCat's included Google application. Each user approves their own account in the browser. Making a shared Google application public for Drive is complex, so Google may refuse -the sign-in; see [what to do](docs/installation.md#google-shows-an-unverified-app-warning). +the sign-in. See [what to do](docs/installation.md#google-shows-an-unverified-app-warning). You can also create your own Desktop client as explained in the -[installation guide](docs/installation.md). Connect your account, then choose a folder: +[installation guide](docs/installation.md). Connect your account, then choose a folder to import for search: ```sh drive personal session start @@ -55,23 +123,27 @@ For Google Cloud setup and an isolated first run, follow the [browser sign-in and live validation guide](docs/dev/GOOGLE_OAUTH.md). Sign-in opens the system browser and receives Google's callback on a temporary loopback port. -`--no-browser` prints the URL. `drive.readonly` grants account-wide reading; our selected-folder -scope limits ingestion. Sync reads remote files. Optional remote management commands need a -new sign-in with `session start --grant write`; history events need `session start --grant activity`. +`--no-browser` prints the URL. `drive.readonly` grants account-wide reading, and our selected-folder +scope limits ingestion. Sync reads remote files. Mirrors and other remote changes need a +new sign-in with `session start --grant write`, and history events need `session start --grant activity`. Credentials use the OS keyring. Where it fails, drive uses an owner-only private file without -asking and says so once; `--credential-storage file` chooses the file outright, not recommended. Tokens never enter regular config, output -or diagnostics. Your own Google app replaces the bundled one with `session start --client-file` or `--client-id`, -`DRIVE_GOOGLE_CLIENT_ID` and `DRIVE_GOOGLE_CLIENT_SECRET`, or the `google_client_id` setting, in that order. The included Desktop -client identity is public application metadata, separate from private user tokens. If you create -your own Desktop client and leave it in Testing, Google usually ends its sign-ins after seven days. +asking and says so once. `--credential-storage file` chooses the file outright, not recommended. Tokens never enter +regular config, output or diagnostics. Your own Google app replaces the bundled one with `session start --client-file` +or `--client-id`, `DRIVE_GOOGLE_CLIENT_ID` and `DRIVE_GOOGLE_CLIENT_SECRET`, or the `google_client_id` setting, in that +order. The included Desktop client identity is public application metadata, separate from private user tokens. If you +create your own Desktop client and leave it in Testing, Google usually ends its sign-ins after seven days. [Google OAuth guide](https://developers.google.com/identity/protocols/oauth2/native-app), [Drive permissions](https://developers.google.com/workspace/drive/api/guides/api-specific-auth). Use `drive work …` for another account. Each Google account has one local profile. `drive session list` lists configured profiles. `session end` removes local sign-in while retaining cached data and configuration so re-login preserves document identities. `account remove --keep-data` or `--delete-data` goes -further: it revokes the sign-in at Google and forgets the profile, and `--delete-data` also deletes its snapshots. +further. It revokes the sign-in at Google and forgets the profile, and `--delete-data` also deletes its snapshots. + +Sources supported for import now: native Google Docs and Sheets, PDF, docx, xlsx, CSV, TSV, and uploaded +Markdown or TXT. Other types and shortcuts are reported as skipped, and shortcuts are not followed outside the +selected scope. ## Search and export @@ -85,11 +157,12 @@ drive personal status --json drive commands sync --json ``` -Search results include the original Google URL. `documents show`, `list` and `export` print `synced_at` and `age_days`; a copy older than a day adds `missing`, `next` and `meta.complete: false`. `documents show` includes each tab's text, ID -and title. Native Markdown exports are saved separately from the all-tab text used for indexing. +Search results include the original Google URL. `documents show`, `list` and `export` print `synced_at` and +`age_days`. A copy older than a day adds `missing`, `next` and `meta.complete: false`. `documents show` includes each +tab's text, ID and title. Native Markdown exports are saved separately from the all-tab text used for indexing. Export refuses to overwrite an existing destination file. -Semantic search uses the shared local text model (about 135 MB). Download it once; it needs no profile or sign-in, +Semantic search uses the shared local text model (about 135 MB). Download it once. It needs no profile or sign-in, and every WireCat CLI shares it: ```sh @@ -97,7 +170,7 @@ drive models download e5-small drive personal sync --embed ``` -Drive never downloads a model on its own; a missing one is reported. `--exact` searches words without semantic +Drive never downloads a model on its own, and a missing one is reported. `--exact` searches words without semantic retrieval. ## Keep it current @@ -108,7 +181,7 @@ drive personal folders remove FOLDER_ID drive personal sync --json ``` -A batch is persisted before processing; interrupted work resumes next run. Progress is saved +A batch is persisted before processing, and interrupted work resumes next run. Progress is saved every 25 files or 2 seconds, so a killed sync redoes at most that many. The first walk of the chosen folders is saved as it goes, and an interrupted walk continues from the folders it had not listed yet. The change cursor advances when the batch completes. Incomplete discovery preserves the prior checkpoint and @@ -116,33 +189,8 @@ documents. A per-profile heartbeat lock prevents simultaneous syncs and recovers Confirmed removals and scope exits remove sources from search and delete their snapshots. Removing the last selected folder reconciles to an empty cache on the next sync. Unsupported, -restricted and oversized sources have explicit coverage status. Transient failures remain pending; -a partial sync with errors exits nonzero. Doc IDs, rather than names, distinguish duplicates. - -## Storage and coverage - -The shared path helper chooses platform-appropriate config, data and cache directories under -drive-cli. Override with `DRIVE_CONFIG_DIR`, `DRIVE_STATE_DIR` and `DRIVE_CACHE_DIR`. Snapshots are -`profiles/