diff --git a/RELEASING.md b/RELEASING.md index 1a48e82..2837553 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -49,8 +49,8 @@ published. If it ever doesn't fit your runner setup, fall back to Option A. ## After a release The skill installer defaults to `EMCLI_VERSION=v0.4.0`. When you cut a different version, either -publish under that tag or update the default in `skills/emcli/scripts/install.sh` (and the note in -`skills/emcli/references/install.md`). +publish under that tag or update the default in `skills/emcli/scripts/install.sh` (and the options +table in `skills/emcli/AGENTIC-MANUAL.md`). ## Versioning diff --git a/skills/emcli/AGENTIC-MANUAL.md b/skills/emcli/AGENTIC-MANUAL.md new file mode 100644 index 0000000..f21a0ca --- /dev/null +++ b/skills/emcli/AGENTIC-MANUAL.md @@ -0,0 +1,99 @@ +# emcli — setup manual (for agents) + +Read this **once**, when emcli isn't set up yet (the binary isn't installed, or you only have +`SKILL.md` from being pointed at the repo). The recurring "how to read and send mail" lives in +`SKILL.md` — don't reload this file for normal use. + +## 1. Get this skill's files + +This skill is a folder, not a single file: it ships `AGENTIC-MANUAL.md` (this file), a `scripts/` +directory, and a `references/` directory. If you were pointed at the repository and have only +`SKILL.md` in context, fetch what you need before proceeding. + +Every `scripts/…` and `references/…` path mentioned anywhere in this skill is **relative to the +skill directory**, whose raw base URL is: + +``` +https://gitea.dcglab.co.uk/steve/emcli/raw/branch/main/skills/emcli/ +``` + +So a file that isn't already on disk can be fetched from `/`. The files are: + +| Path | Purpose | +|---|---| +| `SKILL.md` | The lean, everyday usage guide | +| `AGENTIC-MANUAL.md` | This setup guide (one-time) | +| `scripts/install.sh` | Installs the emcli binary | +| `references/commands.md` | Full agent command reference (flags, JSON shapes, error codes) | + +To enumerate the directory programmatically (then recurse into `scripts` and `references`), use the +Gitea contents API: `https://gitea.dcglab.co.uk/api/v1/repos/steve/emcli/contents/skills/emcli`. + +## 2. Install the binary + +First check whether it's already installed: `emcli version`. If that prints a version, skip to +step 3. + +If you have the skill files locally: + +```bash +bash scripts/install.sh +``` + +If you only have this manual (pointed at the repo), fetch the installer first, then run it: + +```bash +curl -fsSL https://gitea.dcglab.co.uk/steve/emcli/raw/branch/main/skills/emcli/scripts/install.sh -o emcli-install.sh +bash emcli-install.sh +``` + +`install.sh` detects your OS/arch, downloads the matching release binary, verifies its SHA-256 +checksum, makes it executable in `~/.local/bin` (ensure that's on your PATH), and confirms it runs. + +**Installer options** (environment variables): + +| Variable | Default | Purpose | +|---|---|---| +| `EMCLI_VERSION` | `v0.4.0` | Release tag to fetch | +| `EMCLI_BASE_URL` | `https://gitea.dcglab.co.uk/steve/emcli` | Repo base URL | +| `EMCLI_INSTALL_DIR` | `$HOME/.local/bin` | Install location | + +**Build from source instead** (needs Go; the binary is CGO-free): + +```bash +git clone https://gitea.dcglab.co.uk/steve/emcli && cd emcli +CGO_ENABLED=0 go build -o emcli ./cmd/emcli # then move ./emcli onto your PATH +``` + +## 3. Confirm the encryption key is present + +emcli needs `EMCLI_KEY` (a base64-encoded 32-byte AES key) to touch its database. For agent use, +**the orchestrator that launched you provides it** in the environment. + +- Confirm it's set, without printing it: `test -n "$EMCLI_KEY" && echo present`. +- **Never** read, print, log, pass as an argument, or generate this value. +- If it's empty, stop and tell the user: "emcli needs the `EMCLI_KEY` environment variable set by + your orchestrator; I can't read or create it for you." + +(For a human setting emcli up the first time: generate one with `head -c 32 /dev/urandom | base64` +and store it securely. Account creation and other admin is the human's job — see the project's +`USER-MANUAL.md`.) + +## 4. Find the account(s) + +You refer to an account by name (e.g. `gmail`, `work`). Ask the user which account to use. If the +user permits running admin commands, `emcli doctor` lists the configured accounts and checks that +each one connects and authenticates: + +```bash +emcli doctor # all accounts +emcli doctor --account gmail +``` + +Otherwise, just take the account name from the user and start with the workflow in `SKILL.md`. + +## You're set up + +Installed, key present, account name in hand → switch to `SKILL.md` for the everyday `list` / `get` +/ `search` / `ack` / `send` workflow. You shouldn't need this manual again unless the binary goes +missing. diff --git a/skills/emcli/SKILL.md b/skills/emcli/SKILL.md index f5a3d18..57f73f7 100644 --- a/skills/emcli/SKILL.md +++ b/skills/emcli/SKILL.md @@ -15,31 +15,6 @@ and send mail; the program holds the credentials and enforces the user's rules, password and cannot bypass the limits. Every agent command prints exactly **one line of JSON** and sets its exit code to match. -## First: get this skill's files - -This skill is more than this one file. It ships a `scripts/` and a `references/` directory that the -steps below use. **If you were pointed at the repository and have only this `SKILL.md` in context, -download the rest of the skill's files before proceeding** — fetch the whole `skills/emcli/` -directory, or grab each file as a step calls for it. - -Every `scripts/…` and `references/…` path mentioned in this document is **relative to this skill's -directory**. If a file isn't already on disk, fetch it from this raw base URL + the path: - -``` -https://gitea.dcglab.co.uk/steve/emcli/raw/branch/main/skills/emcli/ -``` - -The files are: - -| Path | Purpose | -|---|---| -| `scripts/install.sh` | Installs the emcli binary | -| `references/commands.md` | Full agent command reference (flags, JSON shapes, error codes) | -| `references/install.md` | Installer options / build from source | - -To enumerate the directory programmatically (then recurse into `scripts` and `references`), use the -Gitea contents API: `https://gitea.dcglab.co.uk/api/v1/repos/steve/emcli/contents/skills/emcli`. - ## Security model — read this first - **You only run agent commands:** `list`, `get`, `search`, `ack`, `send`. Account setup, @@ -48,39 +23,27 @@ Gitea contents API: `https://gitea.dcglab.co.uk/api/v1/repos/steve/emcli/content to help administer. - **Never touch the secret key.** `EMCLI_KEY` is supplied in the environment by whoever launched you. Do not read it, print it, log it, pass it as an argument, or try to generate one. If it is - missing, stop and tell the user (see Setup). + missing, stop and tell the user (see "Files & first run"). - **Some mail is intentionally invisible.** The user may restrict which senders you can see and who you can email. Blocked or filtered results are normal — handle them, don't try to work around them (see Enforcement). -## Setup (do this once per session, before the first command) +## Files & first run -1. **Check the binary is available.** Run `emcli version`. If the command is not found, install it. +This skill ships more than this file. Paths like `AGENTIC-MANUAL.md` and `references/commands.md` +are relative to this skill's directory; if one isn't on disk, fetch it from the raw base URL + path: - If you have the skill files locally: +``` +https://gitea.dcglab.co.uk/steve/emcli/raw/branch/main/skills/emcli/ +``` - ```bash - bash scripts/install.sh - ``` +- **First-time setup** — installing the binary, the `EMCLI_KEY`, finding accounts: read + **`AGENTIC-MANUAL.md`**. Only needed when emcli isn't set up yet. +- **Full command detail** — every flag, JSON shapes, error codes: `references/commands.md`. - If you only have this `SKILL.md` (pointed at the repo), fetch the installer first, then run it: - - ```bash - curl -fsSL https://gitea.dcglab.co.uk/steve/emcli/raw/branch/main/skills/emcli/scripts/install.sh -o emcli-install.sh - bash emcli-install.sh - ``` - - This downloads the binary from the project's releases and puts it on your PATH - (`~/.local/bin` by default). For options, see `references/install.md` (fetch it from the raw base - URL above if you don't have it locally). - -2. **Check the key is present.** Confirm the `EMCLI_KEY` environment variable is set (e.g. - `test -n "$EMCLI_KEY"`). **Do not print its value.** If it is empty, do not proceed — tell the - user: "emcli needs the EMCLI_KEY environment variable set by your orchestrator; I can't read or - create it for you." - -3. **Find out which account(s) exist.** Ask the user for the account name (e.g. `gmail`, `work`), - or, if permitted, run `emcli doctor` once to see configured accounts and that they connect. +**Per-session preflight** (quick): run `emcli version`; if it's not found, set up via +`AGENTIC-MANUAL.md`. Confirm `EMCLI_KEY` is set *without printing it* (`test -n "$EMCLI_KEY"`); if +empty, tell the user their orchestrator must provide it. Then get the account name from the user. ## How to read every result @@ -160,7 +123,7 @@ Defaults: `--folder INBOX`, `--limit 50` (max 500). Dates are RFC 3339 (e.g. **Full reference** (every flag, exact JSON shapes for each command, attachment encoding, error codes, and the enforcement rules): `references/commands.md` — read it from disk, or fetch it from -the raw base URL in "First: get this skill's files" above if you don't have it locally. +the raw base URL in "Files & first run" above if you don't have it locally. ## Enforcement awareness — work *with* the rules diff --git a/skills/emcli/references/install.md b/skills/emcli/references/install.md deleted file mode 100644 index 424d487..0000000 --- a/skills/emcli/references/install.md +++ /dev/null @@ -1,62 +0,0 @@ -# Installing the emcli binary - -The skill's `scripts/install.sh` downloads a prebuilt binary from the project's release assets. - -## Quick install - -```bash -bash scripts/install.sh -``` - -It detects your OS (`linux`/`darwin`/`windows`) and architecture (`amd64`/`arm64`), downloads the -matching asset, verifies its SHA-256 checksum when a `checksums.txt` is published, makes it -executable, and confirms it runs. - -## Options (environment variables) - -| Variable | Default | Purpose | -|---|---|---| -| `EMCLI_VERSION` | `v0.4.0` | Release tag to fetch | -| `EMCLI_BASE_URL` | `https://gitea.dcglab.co.uk/steve/emcli` | Repo base URL | -| `EMCLI_INSTALL_DIR` | `$HOME/.local/bin` | Install location | - -Example — install a specific version to a system directory: - -```bash -EMCLI_VERSION=v0.4.0 EMCLI_INSTALL_DIR=/usr/local/bin bash scripts/install.sh -``` - -## Release asset naming - -The release publishes one binary per platform plus a checksum file: - -``` -emcli_0.4.0_linux_amd64 -emcli_0.4.0_linux_arm64 -emcli_0.4.0_darwin_amd64 -emcli_0.4.0_darwin_arm64 -emcli_0.4.0_windows_amd64.exe -checksums.txt # sha256, one " " line per asset -``` - -> `v0.4.0` and these assets are placeholders until the first tagged release exists. Update -> `EMCLI_VERSION` (or the default in `install.sh`) once a real release is cut. - -## Building from source instead - -If you have Go and prefer to build rather than download: - -```bash -git clone https://gitea.dcglab.co.uk/steve/emcli -cd emcli -CGO_ENABLED=0 go build -o emcli ./cmd/emcli -# then move ./emcli onto your PATH -``` - -## After installing - -`emcli` needs the `EMCLI_KEY` environment variable (a base64-encoded 32-byte AES key) to touch its -database. For agent use, the **orchestrator provides this** — the agent should not generate or read -it. A human setting up emcli for the first time generates one with -`head -c 32 /dev/urandom | base64` and saves it securely. See the project User Manual for full admin -setup.