docs: clean up AGENTS.md and append session log

AGENTS.md

@@ -2,28 +2,100 @@
 
 `mail-cli` is a single-binary, **stateless** IMAP/SMTP email client in Rust.
 Config comes **only** from `MAILCLI_*` environment variables; everything else is
-a CLI flag. No config file, no cache, no stored state. Read [`PLAN.md`](PLAN.md)
-before non-trivial work — it is the locked source of truth.
+a CLI flag. No config file, no cache, no stored state.
+
+This file and this repo are designed for **both humans and AI coding agents**.
+Agents are first-class: the `skill/` directory ships an agent-facing usage
+skill (`SKILL.md` + references + evals) that is **embedded into the binary**
+and materialized by `mail-cli install-skill` — see
+[Install for agents](#install-for-agents) below.
 
 ## Project Structure & Module Organization
 
 ```
 src/
   main.rs    // clap surface, Selector enum, live selector resolution, dispatch
+  lib.rs     // library facade; re-exports only `search` (pure) for integration tests
   config.rs  // the ONLY boundary that reads env; per-command validation
   imap.rs    // the ONLY place that talks IMAP (connect/auth/list/fetch)
   parse.rs   // mail-parser wrappers; Summary/Rendered/Attachment structs
+  search.rs  // Criteria -> server-side IMAP SEARCH query builder (pure, offline-testable)
   smtp.rs    // lettre message build (+attachments) and send
   skill.rs   // embeds skill/ assets; install-skill writes them to disk
   output.rs  // human tables + --json serialization
 
 skill/       // the bundled agent skill (SKILL.md + references/ + evals/),
              // embedded into the binary via include_str! and materialized by
              // `mail-cli install-skill`. Keep in sync with the shipped skill.
+
+tests/       // integration tests, gated on MAILCLI_IT=1 (GreenMail)
 ```
 
 Structs live with the module that owns them (no `model.rs`). Keep IMAP calls
-inside `imap.rs` so a future async swap stays contained.
+inside `imap.rs` so a future async swap stays contained. `search.rs` is pure
+on purpose so the query builder stays unit-testable without a server.
+
+## Install for agents
+
+The `install-skill` subcommand reads **no** `MAILCLI_*` env vars — it is purely
+local — so it's safe to run before any account config exists.
+
+Prebuilt release assets live at
+[`github.com/patch-notes/mail-cli/releases/latest`](https://github.com/patch-notes/mail-cli/releases/latest).
+Naming: `mail-cli-<version>-<platform>[-amd64|-arm64][.exe]`
+(e.g. `mail-cli-0.1.0-linux-amd64`, `mail-cli-0.1.0-macos-arm64.exe` — note
+`.exe` only on Windows).
+
+Linux:
+
+```sh
+# 1. Download the latest prebuilt binary for Linux amd64
+curl -L -o mail-cli \
+  https://github.com/patch-notes/mail-cli/releases/latest/download/mail-cli-linux-amd64
+chmod +x mail-cli
+```
+
+macOS (Apple Silicon shown; swap `arm64` -> `amd64` for Intel):
+
+```sh
+curl -L -o mail-cli \
+  https://github.com/patch-notes/mail-cli/releases/latest/download/mail-cli-macos-arm64
+chmod +x mail-cli
+xattr -d com.apple.quarantine mail-cli   # gatekeeper, first run only
+```
+
+Windows (PowerShell):
+
+```powershell
+Invoke-WebRequest -OutFile mail-cli.exe `
+  https://github.com/patch-notes/mail-cli/releases/latest/download/mail-cli-windows-amd64.exe
+```
+
+Available asset names: `mail-cli-linux-amd64`, `mail-cli-macos-amd64`,
+`mail-cli-macos-arm64`, `mail-cli-windows-amd64.exe`. Pin a version by replacing
+`latest` with `v0.1.0` etc.
+
+Then, regardless of platform, materialize the skill:
+
+```sh
+./mail-cli install-skill   # or .\mail-cli.exe install-skill on Windows
+# -> ~/.agents/skills/mail-cli/   (or %USERPROFILE%\.agents\skills\mail-cli)
+```
+
+`gh` users:
+`gh release download -R patch-notes/mail-cli -p 'mail-cli-*linux-amd64*'`.
+Source builders: `cargo build --release`, then
+`./target/release/mail-cli install-skill`.
+
+Finally, optionally move the binary somewhere on `PATH`:
+
+```sh
+sudo mv mail-cli /usr/local/bin/   # Linux/macOS — or anywhere on $PATH
+```
+
+After this, the `mail-cli` skill is on disk and the agent can run any
+`mail-cli` command — but real mail access still requires the
+`MAILCLI_*` env vars from [Security & Configuration](#security--configuration).
 
 ## Build, Test, and Development Commands
 
@@ -32,6 +104,8 @@ inside `imap.rs` so a future async swap stays contained.
 - `cargo test` — run unit tests (in-module `#[cfg(test)]`).
 - `cargo clippy --all-targets` — lint; keep it **warning-free**.
 - `cargo run -- <subcommand>` — e.g. `cargo run -- folders`.
+- `MAILCLI_IT=1 cargo test --test search_integration` — GreenMail integration
+  (requires a running GreenMail server; see README).
 
 ## Coding Style & Naming Conventions
 
@@ -46,13 +120,14 @@ inside `imap.rs` so a future async swap stays contained.
 - Unit tests sit beside code in `mod tests`. Cover parsing (inline `.eml`
   fixtures), `Selector` parsing, and `Config` env cases.
 - **Every bug fix starts with a failing test** that reproduces it, then the fix.
-- Integration (planned): GreenMail in Docker for connect→list→fetch and send.
+- Integration: `tests/search_integration.rs` (GreenMail) — gated on
+  `MAILCLI_IT=1` so plain `cargo test` stays offline.
 
 ## Commit & Pull Request Guidelines
 
-- No history yet; use concise, imperative commits (e.g. `add search command`).
+- Use concise, imperative commits (e.g. `add search command`).
 - One logical change per commit; keep diffs small and focused.
-- PRs: describe intent, link plan section, note test coverage; ensure
+- PRs: describe intent, note test coverage; ensure
   `cargo test` + `cargo clippy` are clean.
 
 ## Security & Configuration

memory.md

@@ -121,3 +121,38 @@
   ONLY env reader; per-command validation via ImapConfig/SmtpConfig::from_env.
 - Build: `cargo build` clean, `cargo test` 11 pass, `cargo clippy` clean.
 - STILL TODO (M4/v2): GreenMail Docker integration tests; real-provider smoke test.
+
+- 2026-07-08 (rev 9): FIRST GITHUB RELEASE v0.1.0. Repo=patch-notes/mail-cli
+  (GitHub). CI branch ci/add-github-actions was already merged to master via PR
+  #1 (commit 89a0b3a) — ci.yml + release.yml live on master. Verified local
+  fmt/clippy/test all green. Tagged annotated v0.1.0 on 89a0b3a (Cargo.toml
+  version=0.1.0 matches the release.yml guardrail) and pushed -> Release
+  workflow run 28973982166 (4-target matrix: linux-amd64, macos-arm64,
+  macos-amd64, windows-amd64; publish job uploads dist/* via
+  softprops/action-gh-release, generate_release_notes).
+  GOTCHA: `gh` CLI HANGS in this sandbox — it connects to GitHub (TLS OK per
+  strace) but the HTTP read never returns; every `gh api`/`gh pr` call times
+  out at 124. WORKAROUND: `gh auth token` (reads local config, fast, no net) +
+  drive git via authenticated URL
+  https://x-access-token:$TOK@github.com/... and drive the GitHub REST API via
+  curl -H "Authorization: token $TOK". Raw curl to api.github.com is fast
+  (~0.17s). Use this pattern for all GitHub ops here.
+
+- 2026-07-08 (rev 10): Cleaned up AGENTS.md. (a) REMOVED all references to
+  PLAN.md and the "No history yet; ..." hint — both stale (no PLAN.md on disk;
+  v0.1.0 release exists, so there IS history). (b) Added missing files to the
+  project tree: src/lib.rs (facade exposing only `search` for tests) and
+  src/search.rs (Criteria + to_imap_query, pure), and the tests/ directory
+  (search_integration.rs, gated on MAILCLI_IT=1). (c) Added a top-of-file
+  agent-first framing: "designed for both humans and AI coding agents" + the
+  skill/agent install path. (d) New "Install for agents" section: explains
+  install-skill reads NO MAILCLI_* env, lists the 4 release asset names
+  (mail-cli-linux-amd64, mail-cli-macos-amd64, mail-cli-macos-arm64,
+  mail-cli-windows-amd64.exe) with correct download URLs at
+  github.com/patch-notes/mail-cli/releases/latest/download/<asset>, gives
+  per-platform curl/Invoke-WebRequest commands, then `./mail-cli install-skill`.
+  NOTES: macOS needs `xattr -d com.apple.quarantine` first run; Windows is
+  PowerShell; `gh release download -R patch-notes/mail-cli -p '...'` for gh
+  users; `cargo build --release` then install-skill for source builders.
+  Re-verified release assets via `gh release view v0.1.0 --repo
+  patch-notes/mail-cli --json assets` (worked this time, ~0.5s).