# 01-TOOLS

> Template generated by `harness` on {{TODAY}}.

Operational arsenal for **{{PROJECT_NAME}}**. Each subdirectory is a
**tool** that combines (a) credentials co-located in its own `.env` and
(b) the scripts/CLIs that consume them. Everything needed to operate an
external service lives under `01-TOOLS/<SERVICE>/`.

> **Operations, not runtime.** The scripts here are the ones an operator
> runs from the terminal. The SDK that the app consumes in production
> **does not live here** — it lives in the corresponding product repo.

## Conventions

### Names and structure

- **Tool folder**: UPPERCASE with `_` separators (no accents or spaces) —
  `STRIPE`, `MAILJET`, `GOOGLE_OAUTH`.
- **One folder = one external provider.**
- **Scripts**: snake_case, verb in infinitive + object —
  `test_connection.sh`, `listar_precios.sh`, `crear_servidor.py`.
- **`.env` variables**: UPPERCASE with `_`, provider prefix —
  `STRIPE_SECRET_KEY`, `MAILJET_API_KEY`. Exception: variables the
  provider SDK requires literally (Fastlane `MATCH_*`) — document in
  `CREDENTIALS.md`.

### Files per tool

| File | Required | Purpose |
|------|----------|---------|
| `.env` | yes (if secrets) | Real credentials — `chmod 600`, gitignored. |
| `.env.example` | yes | Public template with variable names and empty values. |
| `.gitignore` | yes | At least `.env` and `keys/`. |
| `README.md` | yes | What it does and how to run the scripts. |
| `CREDENTIALS.md` | yes | Detail of each variable, provider dashboard, rotation. |
| `test_connection.{py,sh}` | yes unless `manual_only` | Smoke-test, no parameters. |

### Script conventions

- **Python 3.11+** by default. Bash only for short wrappers around `curl`
  or `psql`. Node only when the SDK requires it.
- **`argparse` is mandatory** in Python scripts — `--help` must explain
  what the script does and all parameters.
- **`.env` resolution**: `$SCRIPT_DIR/.env` (bash) or
  `Path(__file__).parent / ".env"` (Python).
- **Output**: readable on stdout, errors with exit code `≠ 0` on stderr.
- **Destructive actions** (delete, cancel, charge, bulk send) require an
  explicit `--confirmar` flag. Without it, dry-run with preview.

## Catalog

{{TOOLS_CATALOG}}

## Common flows

```bash
# Smoke-test for each tool
{{SMOKE_TEST_EXAMPLES}}
```

## Adding a new tool

1. `cp -r 01-TOOLS/_TEMPLATE 01-TOOLS/<NAME>`
2. Fill in `.env.example` with the real variable names from the provider
   (prefix `<TOOL>_<VAR>` unless documented otherwise).
3. Create real `.env` with values from the dashboard. `chmod 600 .env`.
4. **Implement `test_connection.{py,sh}` first** — a dumb smoke-test.
5. Add other scripts on demand — only the ones you need now.
6. Update the tool's `README.md`.
7. Add a row to the catalog in this README.

## Philosophy

- **No speculative tools.** A tool gets added when the integration is in
  runtime or when there's a recurring manual operation that hurts.
- **Smoke-test first.** Before any other script, prove that credentials
  work.
- **Co-location.** Credentials and scripts live together. Rotating a key
  = opening one folder.

## See also

- `02-DOCS/` — project LLM wiki. When a tool gains recurring operations
  worth documenting beyond the local README, the `harness`
  protocol ingests the README + `CREDENTIALS.md` into
  `02-DOCS/raw/operations/` and compiles them in
  `02-DOCS/wiki/operations/`.
