chore: align repo scaffolding with the package standard

.github/workflows/ci.yml

@@ -1,40 +1,27 @@
-name: CI
+name: ci
 
 on:
-  push:
-    branches: ["**"]
   pull_request:
+  push:
+    branches: [main]
 
 jobs:
-  verify:
+  check:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [24]
+    timeout-minutes: 15
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: actions/setup-node@v4
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: 24
       - uses: oven-sh/setup-bun@v2
       - run: bun install --frozen-lockfile
-      - run: bun run lint
-      - run: bun run format:check
-      - run: bun run typecheck
-      - run: bun run typecheck:e2e
-      - run: bun run test
-      - run: bun run build
-      - name: node smoke
+      - run: bun run check
+      - name: node consumer smoke
         run: |
-          node -e '
-            const major = Number(process.versions.node.split(".")[0]);
-            if (major < 24) {
-              throw new Error("need Node 24+, got " + process.version);
-            }
-            import("./dist/index.js").then((m) => {
-              if (typeof m.createGmailTools !== "function") {
-                throw new Error("missing export: createGmailTools");
-              }
-              console.log("node smoke ok", process.version);
-            });
-          '
+          set -euo pipefail
+          TARBALL="$PWD/$(npm pack --silent)"
+          mkdir -p "$RUNNER_TEMP/c" && cd "$RUNNER_TEMP/c"
+          npm init -y >/dev/null && npm pkg set type=module >/dev/null
+          npm install "$TARBALL"
+          node -e 'import("@corbits/google-tools").then((m) => { for (const n of ["createGmailTools", "createGmailClient", "GmailApiError"]) if (typeof m[n] !== "function") throw new Error("missing export: " + n); })'

.github/workflows/cla.yml

@@ -0,0 +1,53 @@
+name: CLA Assistant
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened, synchronize]
+
+permissions:
+  actions: write
+  contents: write
+  pull-requests: write
+  statuses: write
+
+concurrency:
+  group: cla-${{ github.event.pull_request.number || github.event.issue.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  cla:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Maintainer fast path
+        if: >-
+          github.event_name == 'pull_request_target' &&
+          (contains(fromJSON('["TheGreatAxios","brianjfox"]'), github.event.pull_request.user.login) ||
+           endsWith(github.event.pull_request.user.login, '[bot]'))
+        run: echo "Maintainer or bot pull request; CLA not required."
+      - name: CLA Assistant
+        if: >-
+          ((github.event.comment.body == 'recreate-signatures' ||
+            github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') ||
+           github.event_name == 'pull_request_target') &&
+          !(github.event_name == 'pull_request_target' &&
+            (contains(fromJSON('["TheGreatAxios","brianjfox"]'), github.event.pull_request.user.login) ||
+             endsWith(github.event.pull_request.user.login, '[bot]')))
+        # corbitsdev/cla-assistant-action v2.6.1-node24: upstream v2.6.1 on node24.
+        uses: corbitsdev/cla-assistant-action@ef6d3e51db8232fe93090810f13bde30497c1d74
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          path-to-document: "https://github.com/${{ github.repository }}/blob/main/CLA.md"
+          path-to-signatures: "signatures/version1/cla.json"
+          branch: "cla-signatures"
+          allowlist: TheGreatAxios,brianjfox,*[bot]
+          custom-notsigned-prcomment: >-
+            Thank you for your contribution. Before it can be merged, please read our
+            [Contributor License Agreement](https://github.com/${{ github.repository }}/blob/main/CLA.md)
+            and sign it by posting a new comment on this pull request containing
+            exactly the line below (nothing else):
+          custom-pr-sign-comment: "I have read the CLA Document and I hereby sign the CLA"
+          custom-allsigned-prcomment: "All contributors have signed the CLA."

.gitignore

@@ -1,35 +1,9 @@
-# dependencies (bun install)
-node_modules
-
-# output
-out
-dist
+node_modules/
+dist/
+*.tsbuildinfo
 *.tgz
-
-# code coverage
-coverage
-*.lcov
-
-# logs
-logs
-_.log
-report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
-
-# dotenv environment variable files
+coverage/
 .env
-.env.development.local
-.env.test.local
-.env.production.local
-.env.local
-.local/
-
-# caches
-.eslintcache
-.cache
-*.tsbuildinfo
-
-# IntelliJ based IDEs
-.idea
-
-# Finder (MacOS) folder config
+.env.*
 .DS_Store
+.local/

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
 ```

CLA.md

@@ -0,0 +1,64 @@
+# Contributor License Agreement (CLA)
+
+Version 1.0
+
+This Contributor License Agreement ("Agreement") is entered into between the contributor ("Contributor") and ABK Labs, Inc. ("Maintainer").
+
+By submitting any Contribution to a project maintained by Maintainer, the Contributor agrees to the following terms.
+
+## 1. Definitions
+
+"Contribution" means any source code, object code, documentation, test cases, designs, specifications, bug fixes, enhancements, comments, pull requests, commits, issues containing code, or other materials intentionally submitted to a project maintained by Maintainer.
+
+## 2. Copyright Ownership
+
+The Contributor retains ownership of the Contributor's copyrights in the Contribution.
+
+No transfer of copyright ownership is required by this Agreement.
+
+## 3. License Grant to Maintainer
+
+The Contributor grants Maintainer a perpetual, worldwide, non-exclusive, irrevocable, royalty-free license to:
+
+- use, reproduce, modify, distribute, display, perform, and sublicense the Contribution;
+- combine the Contribution with other software and works;
+- distribute the Contribution under the project's current license;
+- distribute the Contribution under future versions of the project's license;
+- distribute the Contribution under alternative open-source, source-available, commercial, proprietary, or dual-license terms.
+
+## 4. License Grant to the Public
+
+The Contributor agrees that the Contribution may be distributed as part of the applicable project under the project's then-current license terms, including LGPL-2.1 or any successor license adopted by Maintainer.
+
+## 5. Contributor Representations
+
+The Contributor represents and warrants that:
+
+1. The Contributor created the Contribution or otherwise has sufficient rights to submit it.
+2. The Contributor has the legal authority to grant the rights described in this Agreement.
+3. To the best of the Contributor's knowledge, the Contribution does not knowingly infringe the intellectual property rights of any third party.
+4. Any third-party material included in the Contribution has been properly disclosed and is compatible with the rights granted under this Agreement.
+
+## 6. Corporate Contributions
+
+If a Contribution is submitted on behalf of an employer or other legal entity, the person accepting this Agreement represents that they are authorized to bind that entity to this Agreement.
+
+## 7. No Obligation
+
+Maintainer is not obligated to use, distribute, maintain, support, or accept any Contribution.
+
+## 8. Disclaimer
+
+Except as expressly stated in this Agreement, the Contribution is provided "AS IS" without warranties or conditions of any kind.
+
+## 9. Electronic Acceptance
+
+The Contributor agrees that electronic acceptance of this Agreement, including acceptance through a website, source-control platform, click-through process, pull-request workflow, or similar mechanism, shall have the same force and effect as a handwritten signature.
+
+## 10. Governing Law
+
+This Agreement shall be governed by the laws of the State of California, excluding its conflict-of-law provisions.
+
+---
+
+By submitting a Contribution, the Contributor acknowledges that they have read and agree to this Agreement.