docs: trim CONTRIBUTING, rewrite AGENTS.md, drop CLAUDE.md

Author: TheGreatAxios

AGENTS.md

@@ -1,21 +1,42 @@
 # AGENTS.md
 
-Instructions for AI agents working in this repository.
+## Purpose
 
-## Overview
+`@corbits/google-tools` is a Gmail tool pack for Interchange agents: search,
+read, label and draft over the Gmail REST API. It owns the tool definitions,
+input schemas, the Gmail client and the sidecar-bundle entry. It does not own
+OAuth or token storage; the host resolves the `gmail-api` credential and signs
+each request. It never sends mail.
 
-**Corbits Tools for Google** — tooling for Google.
+## Layout
 
-## Conventions
+- `src/client/client.ts`: `createGmailClient`, the typed Gmail REST calls.
+- `src/client/schemas.ts`: arktype schemas for Gmail responses.
+- `src/client/errors.ts`: `GmailApiError`.
+- `src/tools/definitions.ts`: the tool catalog, credential handle and scopes.
+- `src/tools/schemas.ts`: tool input schemas.
+- `src/tools/create-tools.ts`: `createGmailTools`, one handler per tool.
+- `src/tools/models.ts`: Gmail message and thread views returned to the model.
+- `src/tools/drafts.ts`: RFC 822 draft building.
+- `src/sidecar-bundle.ts`: the `./sidecar-bundle` entry the tool-package
+  loader invokes.
+- `src/index.ts`: the root entry.
+- `e2e/`: live Gmail suites, gated on `GMAIL_LIVE_TEST=1`.
 
-- **Runtime:** Bun + TypeScript, ES modules only.
-- Touch only code related to the task.
-- Comment _why_, never _what_.
-- No emojis in code or docs.
+## Rules
 
-## Build & Validation
+- Every tool declares `approval: "ask"`, including read-only ones.
+- No tool sends mail.
+- Tokens never enter tool arguments or results; requests go through the
+  host-resolved credential.
+- Parse every Gmail response with arktype; never `as T` untrusted input.
+- Declare tool definitions and approvals as explicit literals.
+- `exactOptionalPropertyTypes` is on: build results with the key omitted,
+  not set to `undefined`.
 
-```bash
+## Local development
+
+```sh
 bun install
-bun run test
+bun run check
 ```

CLAUDE.md

@@ -2,49 +2,35 @@
 
 ## Development
 
-```bash
+```sh
 bun install
-bun run typecheck
-bun run typecheck:e2e
-bun run test
-bun run build
+bun run check
 ```
 
-The tests inject `fetch` implementations and do not call Gmail.
+`bun run check` runs typecheck, lint, format check and unit tests. `bun run format` rewrites the tree.
+
+Contributors sign the [CLA](CLA.md) on their first PR; the CLA bot explains how.
+
+Unit tests inject `fetch` and never call Gmail. `bun run test:e2e` runs the live
+suite, which skips unless `GMAIL_LIVE_TEST=1`.
 
 ## Live Gmail checks
 
 Use a dedicated Gmail fixture account and a Desktop OAuth client granted only
-`gmail.modify`. The read smoke requires a query that matches exactly one
-one-message thread:
+`gmail.modify`. The fixture query must match exactly one one-message thread:
 
-```bash
+```sh
 GMAIL_LIVE_TEST=1 \
 GMAIL_LIVE_CLIENT_ID='...' \
 GMAIL_LIVE_CLIENT_SECRET='...' \
 GMAIL_LIVE_FIXTURE_QUERY='subject:(interchange-gmail-e2e-fixture)' \
 bun run test:e2e
 ```
 
-The full live suite has been verified against a dedicated Gmail fixture account.
-It exercises every Gmail tool:
-
-- `gmail_search_threads` finds the one-message fixture thread.
-- `gmail_get_thread` and `gmail_get_message` retrieve its metadata.
-- `gmail_list_labels` lists the account labels.
-- `gmail_create_draft` and `gmail_list_drafts` create and find a disposable
-  draft, which the suite then deletes.
-- `gmail_label_message` and `gmail_unlabel_message` add and remove `STARRED`
-  on the fixture message.
-- `gmail_label_thread` and `gmail_unlabel_thread` add and remove `STARRED`
-  on every message in the fixture thread.
-
-Add `GMAIL_LIVE_MUTATION_TEST=1` to run the draft and label checks. The suite
-deletes its draft, restores the fixture labels, and never sends email.
-
-The first run opens Google OAuth and stores the refresh token in the ignored
-`.local/gmail-live-token.json` file. Set `GMAIL_LIVE_TOKEN_FILE` when using a
-different token file. Credentials and message contents are not logged.
+Add `GMAIL_LIVE_MUTATION_TEST=1` for the draft and label checks; the suite
+deletes its draft, restores the fixture labels and never sends email. The first
+run opens Google OAuth and stores the refresh token in the ignored
+`.local/gmail-live-token.json` (override with `GMAIL_LIVE_TOKEN_FILE`).
 
 ## Commit messages
 

CONTRIBUTING.md

@@ -51,7 +51,7 @@ granted it and passes it to the tools. The token stays out of the agent.
   [`@corbits/oauth-core`](https://github.com/corbitsdev/corbits-oauth-core),
   which obtains the Google credential the hub stores.
 
-## Tools
+## Reference
 
 | Tool                    | Purpose                                             |
 | ----------------------- | --------------------------------------------------- |