oto-cli 1.0.0__tar.gz

oto_cli-1.0.0/.claude/settings.local.json

@@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(mkdir:*)",
+      "Bash(source:*)",
+      "Bash(node:*)",
+      "Bash(oto whatsapp:*)",
+      "Bash(oto google:*)",
+      "Skill(claude-api)",
+      "Bash(npm list:*)",
+      "Bash(twilio:*)",
+      "Bash(ngrok:*)",
+      "Bash(sqlite3:*)",
+      "Bash(oto browser:*)",
+      "Bash(oto:*)",
+      "Bash(pipx list:*)",
+      "Bash(hatch build:*)"
+    ]
+  }
+}

oto_cli-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+venv/
+__pycache__/
+*.egg-info/
+dist/
+oto/tools/whatsapp/node/node_modules/
+
+# Secrets
+.otomata/
+secrets.env
+*-token-*.json
+
+# Internal
+PLAN.md

oto_cli-1.0.0/CLAUDE.md

@@ -0,0 +1,117 @@
+# Oto
+
+CLI toolkit for AI agents — covers the long tail of SaaS APIs that don't have a CLI.
+
+Repo: `AlexisLaporte/oto`. Package: `oto-cli` on PyPI. Command: `oto`.
+
+## Philosophy
+
+- **CLI-first**: everything goes through `oto <command>`, no MCP, no server
+- **For AI agents**: JSON on stdout, errors on stderr, composable with pipes
+- **Modular**: each connector is a separate file, auto-discovered at startup
+- **No over-engineering**: no plugin registry, no ABC, no MCP
+
+## Stack
+
+- Python 3.10+, Typer (CLI), Hatchling (build)
+- Google APIs (auth, drive, docs, sheets, slides, gmail, keep)
+- o-browser (browser automation, Patchright) — optional
+- Requests (HTTP), python-dotenv (secrets)
+
+## Architecture
+
+```
+oto/
+├── oto/
+│   ├── cli.py                  # Dynamic command discovery + main()
+│   ├── config.py               # Secrets 3-tier (.otomata/secrets.env)
+│   ├── commands/               # 1 file = 1 sub-command (auto-discovered)
+│   │   ├── google.py           # drive, docs, sheets, slides, gmail, calendar, auth
+│   │   ├── notion.py           # search, page, database
+│   │   ├── browser.py          # linkedin, crunchbase, pappers, indeed, g2
+│   │   ├── sirene.py           # SIRENE API (search, get, stock)
+│   │   ├── search.py           # web, news (serper)
+│   │   ├── enrichment.py       # kaspr, hunter, lemlist
+│   │   ├── pennylane.py        # accounting
+│   │   ├── anthropic.py        # usage, cost, summary
+│   │   ├── company.py          # SIREN lookup multi-source
+│   │   ├── whatsapp.py         # WhatsApp messaging
+│   │   └── skills.py           # Claude Code skills (enable/disable)
+│   └── tools/                  # API clients
+│       ├── google/             # gmail, drive, docs, sheets, slides, calendar, keep
+│       ├── notion/             # pages, databases, search
+│       ├── browser/            # linkedin, crunchbase, pappers, indeed, g2
+│       ├── whatsapp/           # Node.js bridge (whatsapp-web.js)
+│       ├── sirene/             # INSEE SIRENE API
+│       ├── serper/             # Google search (web, news)
+│       ├── anthropic/          # Admin API (usage, costs)
+│       ├── pennylane/          # Accounting
+│       ├── kaspr/, hunter/, lemlist/  # Enrichment & outreach
+│       └── folk/, slack/, resend/     # CRM & messaging
+├── skills/                     # Claude Code skills
+│   └── oto-*/SKILL.md          # LLM instruction manuals
+└── pyproject.toml              # entry point: oto = "oto.cli:main"
+```
+
+## Adding a new connector
+
+A connector = 3 files:
+
+1. **`commands/myservice.py`** — Typer app, exports `app`
+2. **`tools/myservice/`** — API client(s)
+3. **`skills/oto-myservice/SKILL.md`** — LLM instructions
+
+See `docs/create-connector.md` for details.
+
+## Command pattern
+
+Each `commands/*.py` file:
+```python
+import typer
+import json
+from typing import Optional
+
+app = typer.Typer(help="My service description")
+
+@app.command("do-thing")
+def do_thing(
+    query: str = typer.Argument(..., help="What to do"),
+    max_results: int = typer.Option(20, "--max-results", "-n"),
+):
+    """Do a thing."""
+    from oto.tools.myservice.client import MyServiceClient
+    client = MyServiceClient()
+    results = client.do_thing(query=query, max_results=max_results)
+    print(json.dumps(results, indent=2))
+```
+
+Key rules:
+- `app = typer.Typer()` exported, auto-discovered by `cli.py`
+- Tool imports **inside functions** (lazy) so the CLI stays fast
+- Always `print(json.dumps(..., indent=2))` for output
+- Missing secrets raise `ValueError`, caught by `main()` → clean stderr message
+
+## Secrets
+
+3-tier resolution (first found wins):
+1. Environment variables
+2. `.otomata/secrets.env` in project directory (walks up 4 levels)
+3. `~/.otomata/secrets.env` (user-level)
+
+## Google OAuth
+
+Tokens stored in `~/.otomata/google-oauth-token-{name}.json`.
+
+Add an account: `oto google auth <name>` — opens browser for OAuth flow.
+List accounts: `oto google auth --list`.
+
+## Skills (Claude Code)
+
+Skills = SKILL.md files in `skills/oto-*/`, symlinked to `~/.claude/skills/`.
+
+```bash
+oto skills list                    # see status
+oto skills enable --all            # enable all
+oto skills enable oto-google       # enable one
+oto skills disable oto-pennylane   # disable one
+```

oto_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alexis Laporte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oto_cli-1.0.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: oto-cli
+Version: 1.0.0
+Summary: CLI toolkit for AI agents — covers the long tail of SaaS APIs that don't have a CLI
+Project-URL: Repository, https://github.com/AlexisLaporte/oto
+Author: Alexis Laporte
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,api,automation,cli,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40.0; extra == 'all'
+Requires-Dist: gkeepapi>=0.16.0; extra == 'all'
+Requires-Dist: google-api-python-client>=2.0.0; extra == 'all'
+Requires-Dist: google-auth-oauthlib>=1.0.0; extra == 'all'
+Requires-Dist: google-auth>=2.0.0; extra == 'all'
+Requires-Dist: o-browser; extra == 'all'
+Requires-Dist: pandas>=1.5.0; extra == 'all'
+Requires-Dist: pyarrow>=10.0.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40.0; extra == 'anthropic'
+Provides-Extra: browser
+Requires-Dist: o-browser; extra == 'browser'
+Provides-Extra: google
+Requires-Dist: gkeepapi>=0.16.0; extra == 'google'
+Requires-Dist: google-api-python-client>=2.0.0; extra == 'google'
+Requires-Dist: google-auth-oauthlib>=1.0.0; extra == 'google'
+Requires-Dist: google-auth>=2.0.0; extra == 'google'
+Provides-Extra: stock
+Requires-Dist: pandas>=1.5.0; extra == 'stock'
+Requires-Dist: pyarrow>=10.0.0; extra == 'stock'
+Description-Content-Type: text/markdown
+
+# oto — CLI toolkit for AI agents
+
+Your LLM already uses `gh` for GitHub, `aws` for AWS, `gcloud` for GCP.
+**oto** covers the long tail — the SaaS products that don't have a CLI.
+
+Each connector ships with a **SKILL.md** — an instruction manual that teaches your AI agent how to use it. Run `oto skills enable --all` and your Claude Code / Cursor / Aider gets instant context on 15+ APIs.
+
+## Why CLI over MCP?
+
+| | CLI | MCP |
+|---|---|---|
+| Token cost | ~80 tokens (prompt + `--help`) | 4-32x more (full schema in context) |
+| Reliability | 100% | ~72% ([source](https://scalekit.com)) |
+| Setup | `pipx install oto-cli` | Server + transport + config |
+| Composability | Pipes: `oto sirene search "fintech" \| jq '.[]'` | None |
+| Works with | Every LLM, every framework | MCP-compatible clients only |
+
+## Installation
+
+```bash
+# Standalone CLI
+pipx install oto-cli
+
+# With specific connectors
+pipx install "oto-cli[google,browser]"
+
+# All connectors
+pipx install "oto-cli[all]"
+
+# Development
+git clone https://github.com/AlexisLaporte/oto.git
+cd oto && pip install -e ".[all]"
+```
+
+## Connectors
+
+| Command | What it does | Extra |
+|---------|-------------|-------|
+| `oto google` | Gmail, Drive, Docs, Sheets, Slides, Calendar | `google` |
+| `oto browser` | LinkedIn, Crunchbase, Pappers, Indeed, G2 | `browser` |
+| `oto notion` | Search, pages, databases | — |
+| `oto sirene` | French company data (INSEE SIRENE) | — |
+| `oto search` | Web & news search (Serper/Google) | — |
+| `oto enrichment` | Contact enrichment (Kaspr, Hunter, Lemlist) | — |
+| `oto pennylane` | Accounting (Pennylane API) | — |
+| `oto anthropic` | API usage & cost tracking | `anthropic` |
+| `oto whatsapp` | Send & read WhatsApp messages | — |
+| `oto folk` | Folk CRM (contacts, companies, deals) | — |
+| `oto company` | French company lookup (multi-source) | — |
+| `oto audio` | Audio recording, transcription, summaries | — |
+
+Connectors without an "Extra" only need `requests` (included in base install).
+
+## Quick start
+
+```bash
+# Configure secrets
+mkdir -p ~/.otomata
+cat > ~/.otomata/secrets.env << 'EOF'
+SERPER_API_KEY=xxx
+NOTION_API_KEY=secret_xxx
+SIRENE_API_KEY=xxx
+EOF
+
+# Check config
+oto config
+
+# Search the web
+oto search web "AI agents 2026"
+
+# Google OAuth setup (per account)
+oto google auth myaccount
+oto google gmail-search "from:bob" -a myaccount
+
+# Browse LinkedIn
+oto browser linkedin profile https://linkedin.com/in/someone
+
+# French company data
+oto sirene search "fintech"
+```
+
+## Skills for AI agents
+
+The killer feature: each connector comes with a SKILL.md that teaches your LLM how to use it.
+
+```bash
+# Enable all skills for Claude Code
+oto skills enable --all
+
+# Or pick specific ones
+oto skills enable oto-google
+oto skills enable oto-search
+```
+
+Once enabled, your AI agent sees these instructions in its context and knows exactly which `oto` commands to use, with what arguments, and what output to expect.
+
+## Create your own connector
+
+A connector is 3 files:
+
+```
+oto/commands/myservice.py    # CLI commands (Typer app)
+oto/tools/myservice/         # API client
+skills/oto-myservice/SKILL.md  # LLM instructions
+```
+
+See [docs/create-connector.md](docs/create-connector.md) for the full guide.
+
+## How it works
+
+**Auto-discovery** — `cli.py` scans `commands/` at startup. Any Python file exporting a Typer `app` becomes a sub-command. No registry, no config. Drop a file, it appears in `oto --help`.
+
+**Three types of connectors** (same CLI contract: JSON stdout, lazy imports, `get_secret()`):
+- **API** — call REST APIs via `requests`. Each client handles auth/pagination/rate-limiting as the API requires. (notion, sirene, search, pennylane, folk...)
+- **Browser** — automate a real browser for sites without an API. Async, require `oto-cli[browser]`. (linkedin, crunchbase, pappers, indeed, g2)
+- **SDK** — use an official client library. Currently Google Workspace via `google-api-python-client` + OAuth2. Require `oto-cli[google]`.
+
+**Secrets** — 3-tier resolution (first found wins):
+1. Environment variables
+2. `.otomata/secrets.env` in project directory (walks up 4 levels)
+3. `~/.otomata/secrets.env` (user-level)
+
+**Output contract** — every command prints JSON to stdout, errors to stderr. Composable with `jq`, pipes, scripts.
+
+**Lazy imports** — tool clients are imported inside functions, so the CLI starts fast regardless of how many connectors are installed.
+
+See [docs/concepts.md](docs/concepts.md) for the full architecture guide.
+
+## License
+
+MIT

oto_cli-1.0.0/README.md

@@ -0,0 +1,131 @@
+# oto — CLI toolkit for AI agents
+
+Your LLM already uses `gh` for GitHub, `aws` for AWS, `gcloud` for GCP.
+**oto** covers the long tail — the SaaS products that don't have a CLI.
+
+Each connector ships with a **SKILL.md** — an instruction manual that teaches your AI agent how to use it. Run `oto skills enable --all` and your Claude Code / Cursor / Aider gets instant context on 15+ APIs.
+
+## Why CLI over MCP?
+
+| | CLI | MCP |
+|---|---|---|
+| Token cost | ~80 tokens (prompt + `--help`) | 4-32x more (full schema in context) |
+| Reliability | 100% | ~72% ([source](https://scalekit.com)) |
+| Setup | `pipx install oto-cli` | Server + transport + config |
+| Composability | Pipes: `oto sirene search "fintech" \| jq '.[]'` | None |
+| Works with | Every LLM, every framework | MCP-compatible clients only |
+
+## Installation
+
+```bash
+# Standalone CLI
+pipx install oto-cli
+
+# With specific connectors
+pipx install "oto-cli[google,browser]"
+
+# All connectors
+pipx install "oto-cli[all]"
+
+# Development
+git clone https://github.com/AlexisLaporte/oto.git
+cd oto && pip install -e ".[all]"
+```
+
+## Connectors
+
+| Command | What it does | Extra |
+|---------|-------------|-------|
+| `oto google` | Gmail, Drive, Docs, Sheets, Slides, Calendar | `google` |
+| `oto browser` | LinkedIn, Crunchbase, Pappers, Indeed, G2 | `browser` |
+| `oto notion` | Search, pages, databases | — |
+| `oto sirene` | French company data (INSEE SIRENE) | — |
+| `oto search` | Web & news search (Serper/Google) | — |
+| `oto enrichment` | Contact enrichment (Kaspr, Hunter, Lemlist) | — |
+| `oto pennylane` | Accounting (Pennylane API) | — |
+| `oto anthropic` | API usage & cost tracking | `anthropic` |
+| `oto whatsapp` | Send & read WhatsApp messages | — |
+| `oto folk` | Folk CRM (contacts, companies, deals) | — |
+| `oto company` | French company lookup (multi-source) | — |
+| `oto audio` | Audio recording, transcription, summaries | — |
+
+Connectors without an "Extra" only need `requests` (included in base install).
+
+## Quick start
+
+```bash
+# Configure secrets
+mkdir -p ~/.otomata
+cat > ~/.otomata/secrets.env << 'EOF'
+SERPER_API_KEY=xxx
+NOTION_API_KEY=secret_xxx
+SIRENE_API_KEY=xxx
+EOF
+
+# Check config
+oto config
+
+# Search the web
+oto search web "AI agents 2026"
+
+# Google OAuth setup (per account)
+oto google auth myaccount
+oto google gmail-search "from:bob" -a myaccount
+
+# Browse LinkedIn
+oto browser linkedin profile https://linkedin.com/in/someone
+
+# French company data
+oto sirene search "fintech"
+```
+
+## Skills for AI agents
+
+The killer feature: each connector comes with a SKILL.md that teaches your LLM how to use it.
+
+```bash
+# Enable all skills for Claude Code
+oto skills enable --all
+
+# Or pick specific ones
+oto skills enable oto-google
+oto skills enable oto-search
+```
+
+Once enabled, your AI agent sees these instructions in its context and knows exactly which `oto` commands to use, with what arguments, and what output to expect.
+
+## Create your own connector
+
+A connector is 3 files:
+
+```
+oto/commands/myservice.py    # CLI commands (Typer app)
+oto/tools/myservice/         # API client
+skills/oto-myservice/SKILL.md  # LLM instructions
+```
+
+See [docs/create-connector.md](docs/create-connector.md) for the full guide.
+
+## How it works
+
+**Auto-discovery** — `cli.py` scans `commands/` at startup. Any Python file exporting a Typer `app` becomes a sub-command. No registry, no config. Drop a file, it appears in `oto --help`.
+
+**Three types of connectors** (same CLI contract: JSON stdout, lazy imports, `get_secret()`):
+- **API** — call REST APIs via `requests`. Each client handles auth/pagination/rate-limiting as the API requires. (notion, sirene, search, pennylane, folk...)
+- **Browser** — automate a real browser for sites without an API. Async, require `oto-cli[browser]`. (linkedin, crunchbase, pappers, indeed, g2)
+- **SDK** — use an official client library. Currently Google Workspace via `google-api-python-client` + OAuth2. Require `oto-cli[google]`.
+
+**Secrets** — 3-tier resolution (first found wins):
+1. Environment variables
+2. `.otomata/secrets.env` in project directory (walks up 4 levels)
+3. `~/.otomata/secrets.env` (user-level)
+
+**Output contract** — every command prints JSON to stdout, errors to stderr. Composable with `jq`, pipes, scripts.
+
+**Lazy imports** — tool clients are imported inside functions, so the CLI starts fast regardless of how many connectors are installed.
+
+See [docs/concepts.md](docs/concepts.md) for the full architecture guide.
+
+## License
+
+MIT

oto_cli-1.0.0/TODO.md

@@ -0,0 +1,45 @@
+# TODO / Roadmap
+
+## Browser automation
+
+### Multi-backend support
+Currently using Patchright (undetectable Playwright). Consider adding alternative backends:
+
+- **Vercel Agent-Browser** (https://github.com/vercel-labs/agent-browser)
+  - CLI Rust/Node, fast
+  - `snapshot` command returns accessibility tree (AI-friendly)
+  - Stateful across commands
+  - `--profile` for session persistence
+  - Installation: `npm install -g agent-browser`
+
+  Could be useful for AI agent workflows where we want structured DOM info rather than raw HTML/text.
+
+- **Chrome DevTools MCP** (https://github.com/anthropics/chrome-devtools-mcp)
+  - 26 outils : navigation, input, debugging, network, performance, emulation
+  - Accès direct aux DevTools (console, network, DOM)
+  - Tests E2E déclaratifs en YAML
+  - Installation: `claude mcp add chrome-devtools npx chrome-devtools-mcp@latest`
+
+  Complémentaire à Patchright : utile pour debugging dev web, pas pour scraping (nécessite Chrome UI).
+
+### Ideas
+- [ ] Abstract backend selection in BrowserClient (patchright vs agent-browser)
+- [ ] Add `snapshot()` method that returns structured accessibility tree (format AI-friendly)
+- [ ] Évaluer Chrome DevTools MCP pour tests E2E (complémentaire à Patchright)
+
+## Scrapers
+
+- [x] Indeed jobs scraper
+- [x] LinkedIn profile scraper
+- [x] Crunchbase, Pappers, G2 scrapers
+- [ ] Generic "login + navigate + extract" pattern
+
+## Google tools
+
+- [ ] Calendar integration
+- [ ] Gmail (or use MCP server?)
+
+## Notion tools
+
+- [ ] Batch page creation
+- [ ] Database sync with external sources

oto_cli-1.0.0/docs/concepts.md

@@ -0,0 +1,136 @@
+# Concepts
+
+## Why oto exists
+
+LLMs are good at using CLI tools — they were trained on billions of terminal interactions. For popular tools (`gh`, `aws`, `gcloud`, `docker`), the LLM already knows the commands.
+
+But most SaaS products don't have a CLI. When an AI agent needs to interact with Notion, Pennylane, LinkedIn, or SIRENE, it has two options:
+1. **MCP** — a protocol that puts the full API schema in the LLM's context window (expensive: 4-32x more tokens, 72% reliability)
+2. **CLI** — a command-line tool the LLM calls via Bash (cheap: ~80 tokens, 100% reliability)
+
+**oto is option 2.** One CLI, many connectors, each with an LLM instruction manual (SKILL.md).
+
+## Architecture
+
+### Auto-discovery
+
+`cli.py` scans `oto/commands/` at startup. Any `.py` file that exports `app = typer.Typer()` becomes a sub-command:
+
+```
+commands/google.py   → oto google ...
+commands/search.py   → oto search ...
+commands/stripe.py   → oto stripe ...   (you add this)
+```
+
+No registry, no config. Drop a file, it works.
+
+### Connector anatomy
+
+A connector is 3 parts:
+
+```
+commands/myservice.py          # CLI layer (Typer commands)
+tools/myservice/client.py      # API client (business logic)
+skills/oto-myservice/SKILL.md  # LLM instructions
+```
+
+**Commands** define the CLI surface — arguments, options, help text. They import the tool client lazily (inside the function body) so the CLI starts fast.
+
+**Tool clients** talk to the API. They use `get_secret()` for auth and return plain Python dicts/lists.
+
+**Skills** are markdown files that teach the LLM how to use the connector. They get symlinked into `~/.claude/skills/` and appear in the agent's context.
+
+### Connector types
+
+There are 3 types of connectors. They differ in how the tool client talks to the service, but the CLI contract is always the same: JSON on stdout, lazy imports, `get_secret()` for auth.
+
+**API connectors** — call a REST API via `requests`. Most connectors are this type. Auth, rate limiting, and pagination depend on the provider — each client handles it as the API requires.
+
+```
+tools/serper/client.py     → requests + X-API-KEY header
+tools/notion/client.py     → requests + Bearer token + cursor pagination
+tools/pennylane/client.py  → requests + Bearer token + retry on 429
+tools/folk/client.py       → requests + Bearer token + Retry-After header
+tools/kaspr/client.py      → requests + Bearer token
+tools/hunter/client.py     → requests + query param api_key
+```
+
+**Browser connectors** — automate a real browser (via [o-browser](https://github.com/AntMusic/o-browser)) for sites that don't have an API, or where the API is too limited. They inherit from `BrowserClient`, are async, and use context managers. Commands wrap them in `asyncio.run()`.
+
+```
+tools/browser/linkedin.py   → cookie auth, file-based rate limiting
+tools/browser/crunchbase.py → cookie auth, session persistence
+tools/browser/pappers.py    → no auth, Cloudflare handling
+tools/browser/indeed.py     → no auth, multi-country
+tools/browser/g2.py         → no auth, review scraping
+```
+
+Require the `browser` extra: `pip install oto-cli[browser]`.
+
+**SDK connectors** — use an official SDK instead of raw HTTP. Currently only Google Workspace, which uses `google-api-python-client` with OAuth2 tokens stored in `~/.otomata/google-oauth-token-{name}.json`.
+
+```
+tools/google/gmail/      → google-api-python-client (OAuth2)
+tools/google/drive/      → google-api-python-client (OAuth2)
+tools/google/docs/       → google-api-python-client (OAuth2)
+tools/google/calendar/   → google-api-python-client (OAuth2)
+```
+
+Require the `google` extra: `pip install oto-cli[google]`.
+
+**There's no base class.** Each client implements what its API requires — the only shared contract is on the CLI side (JSON output, lazy imports, `get_secret()`).
+
+### Secrets
+
+3-tier resolution — first found wins:
+
+| Priority | Location | Scope |
+|----------|----------|-------|
+| 1 | Environment variable | Session |
+| 2 | `.otomata/secrets.env` (project dir, walks up 4 levels) | Project |
+| 3 | `~/.otomata/secrets.env` | User |
+
+```bash
+# Setup
+mkdir -p ~/.otomata
+echo "SERPER_API_KEY=xxx" >> ~/.otomata/secrets.env
+
+# Check
+oto config
+```
+
+In code, `get_secret("SERPER_API_KEY")` resolves through all 3 tiers. If the key is missing, it raises a `ValueError` with instructions — caught by `main()` for a clean error message.
+
+### Output contract
+
+Every command prints JSON to stdout:
+
+```bash
+oto search web "AI agents" | jq '.[0].title'
+oto sirene search "fintech" | jq '.[] | .siren'
+```
+
+Errors go to stderr. Exit code 0 = success, 1 = error. This makes oto composable with standard Unix tools.
+
+### Skills (SKILL.md)
+
+A SKILL.md is a markdown file with YAML frontmatter:
+
+```markdown
+---
+name: oto-search
+description: Web and news search via Serper (Google)
+---
+
+# Search
+Use `oto search` commands via Bash.
+...
+```
+
+When symlinked to `~/.claude/skills/`, the LLM sees this file in its context and learns when and how to use the connector. The `description` field is what the LLM uses to decide if the skill is relevant.
+
+```bash
+oto skills enable oto-search    # creates symlink
+oto skills disable oto-search   # removes symlink
+oto skills list                 # shows status
+```