@clize/clize 0.32.0 → 0.34.0

package/README.md

@@ -11,7 +11,7 @@ npm i -g @clize/clize
 clize install          # wire clize into your coding agent (Claude Code / Codex)
 ```
 
-`clize install` is the step that makes your agent actually *reach for* clize — a binary on your `PATH` doesn't tell the agent it exists. By default it drops clize's skill (when to use it + the safety gates) into each agent's skills dir; the skill is lightweight — only its short description sits in context until something triggers it. It auto-detects Claude Code (`~/.claude`) and Codex (`~/.codex`); scope with `--claude` / `--codex`, preview with `--dry-run`. Add `--mcp` to also register the `clize-mcp` server — opt-in, because an MCP server's tool list stays in context every session.
+`clize install` is the step that makes your agent actually *reach for* clize — a binary on your `PATH` doesn't tell the agent it exists. By default it drops clize's skill (when to use it + the safety gates) into each agent's skills dir; the skill is lightweight — only its short description sits in context until something triggers it. It auto-detects Claude Code (`~/.claude`), Codex (`~/.codex`) and Pi (`~/.pi`); Codex and Pi share the open `~/.agents/skills` directory, so any agent that reads it gets the skill too. Scope with `--claude` / `--codex` / `--pi`, preview with `--dry-run`. Add `--mcp` to also register the `clize-mcp` server — opt-in, because an MCP server's tool list stays in context every session.
 
 Update later with one command — pulls the latest release and refreshes the skill together:
 
@@ -21,18 +21,20 @@ clize update            # or `clize update --check` to only check for a newer ve
 
 If something looks stale after an update, `clize doctor` prints what's installed vs what's actually running — CLI version (and the upgrade command that works for your install manager: volta / pnpm / asdf / …), skill drift, and control-plane reachability.
 
+Output is English by default. `CLIZE_LANG=zh` (or a `zh*` system locale) switches the CLI, the MCP tool descriptions and the control plane's messages to Chinese; the dictionary lives in `src/i18n/zh.ts`.
+
 ## Quickstart (hosted)
 
 Log in and go — your agent never touches Cloudflare:
 
 ```bash
-clize login                       # browser authorize → creates your account, saves a clize key
-clize check                       # ✓ connected to the hosted backend
-clize claim acme                  # free handle: acme.clize.app (site placeholder; add --email for support@)
-clize init --handle acme          # bind this directory — deploy / email send infer domain & from
-clize deploy ./site               # ship a static site → https://acme.clize.app
-clize status                      # who's waiting, this month's spend
-clize email inbox acme.clize.app  # read what customers sent
+clize login                              # browser authorize; the first login creates your account
+clize claim acme --email                 # free identity: acme.clize.app + support@acme.clize.app
+clize init --handle acme                 # bind this directory (deploy / send / inbox infer the rest)
+clize email inbox --wait-for "verify"    # the agent signs up somewhere with support@acme.clize.app and reads the code here
+clize status                             # who is waiting (real people + codes only), this month's spend
+clize email send --to a@b.com --subject "Re: …" --text "…"   # draft only; add --confirm once you approve
+clize deploy ./site                      # ship a static site → https://acme.clize.app
 ```
 
 ## Hosted — just log in
@@ -54,20 +56,20 @@ A few specifics worth knowing:
 
 | Area | Commands |
 |---|---|
-| **Claim** | `clize claim <slug>` — first-come, free `<slug>.clize.app` handle: name + site placeholder. A receiving `support@` is one more step (`--email` at claim time, or `clize email setup <handle>` later) — it is opt-in because each inbox costs 4 DNS records in the shared `clize.app` zone, and that zone is the whole platform's free-handle capacity |
+| **Identity** | `clize claim <slug> --email` — a first-come, free identity for your agent: `<slug>.clize.app` (site placeholder) plus a receiving `support@<slug>.clize.app`. Without `--email` you get the name and the site only (`clize email setup <handle>` opens the inbox later) — inbound is opt-in because each inbox costs 4 DNS records in the shared `clize.app` zone, and that zone is the whole platform's free-handle capacity |
 | **Domains** | `clize domain search / tlds / buy / import / list` |
-| **Email** | `clize email address add <addr>` opens a mailbox in one step (object + receiving) on any domain you own — as many per domain as you need (`ops@`, `sales@`, one per agent or per person); `--forward me@gmail.com` copies mail to a personal inbox, `--owner <member>` makes it someone's private mailbox. `support@<slug>.clize.app` is available on any claimed handle via `clize email setup <handle>` (or `clize claim <slug> --email`). Read with `inbox` (triaged: promos / notices / spam are filtered, `--all` shows everything) / `show` / `thread` / `search`, correct triage with `mark`, send with `send` (`--attach`). Mail is stored permanently and indexed. **Multi-user**: `clize members invite alice@corp.com --mailbox alice@<domain>` lets a person log in and use their own mailbox; owners/admins see every mailbox in the account. **Per-agent keys**: `clize email key create --scope read,send --address ops@<domain>`. See [MAILBOX.md](MAILBOX.md). |
+| **Email** | The mailbox your agent signs up for services with and reads verification codes from (`clize email inbox [domain] --wait-for <text>` polls until the mail arrives), and the inbox real people write to. `clize email address add <addr>` opens a mailbox in one step (object + receiving) on any domain you own — as many per domain as you need (`ops@`, `sales@`, one per agent or per person); `--forward me@gmail.com` copies mail to a personal inbox, `--owner <member>` makes it someone's private mailbox. `support@<slug>.clize.app` is available on any claimed handle via `clize email setup <handle>` (or `clize claim <slug> --email`). Read with `inbox` (triaged: promos / notices / spam are filtered, `--all` shows everything) / `show` / `thread` / `search`, correct triage with `mark`, send with `send` (`--attach`). Mail is stored permanently and indexed. **Multi-user**: `clize members invite alice@corp.com --mailbox alice@<domain>` lets a person log in and use their own mailbox; owners/admins see every mailbox in the account. **Per-agent keys**: `clize email key create --scope read,send --address ops@<domain>`. See [MAILBOX.md](MAILBOX.md). |
 | **Send API** (server-callable) | `POST /v1/email/send` — transactional email from a long-running backend (fly.io / cron), Resend/Postmark-shaped, sending from a domain already in Clize (no second email vendor). Auth is a **scoped send key** (`clize_sk_…`: send-only, lockable to specific domains) — `clize email key create/list/revoke`. No `--confirm` (the human-review gate stays on interactive `email send`). Idempotency-Key, HMAC-signed delivery webhooks (bounce/complaint), RFC 8058 one-click unsubscribe + suppression lists (`email delivery-webhook / suppressions / messages`). See [EMAIL-API.md](EMAIL-API.md). |
 | **Media** | `clize gen image / video / music` — text→image (`gpt-image-2` / `nano-banana-2`, with `--ref` / `--mask` for image-to-image and inpainting), text/image→video (`veo`), text→music (`suno`); long tasks via `gen jobs / status`. Every spend is gated by `--confirm` (`gen budget` pre-approval for hosted is on the roadmap). Results land as local files, ready to `deploy` or `email --attach`. |
 | **Build · site** (hosted methods) | `clize build site start <brief>` — a hosted design system that briefs your agent on a cohesive style *before* it writes the site, so pages land with taste instead of AI-template sludge. Then `build site recommend / list / get / search / review` + `build site stack <stack>` for stack-specific guidance (React / Next / SwiftUI / …). The former `clize design …` spelling still works as a hidden alias. |
 | **Build · clip** (hosted methods) | `clize build clip start <brief>` → your agent writes a shot-by-shot blueprint → `build clip check` (free local lint: continuity, dialogue coverage, timing) → `build clip render --confirm` (💰 one summed quote, batch-generate + merge, resumable). One-off footage stays `gen video`. |
 | **Deploy** | `clize deploy <dir> --domain <host>` — multi-file static sites; free `*.clize.app` or your own domain. Preview locally first with `clize serve <dir>` (proper `Range` support — `<video>` pages actually play in Safari). |
-| **SEO / GEO** (hosted data) | `clize seo keywords <seeds...>` / `competitors <domains...>` / `serp <keyword>` — research data with **no key, no signup, no upstream account**: search volume + difficulty + intent (difficulty banded by what you can actually attack), what competitors live on, and who occupies a results page (an `official_wall` / `definition_wall` / `listicle_window` / `open` verdict from a rule engine, plus the listicles worth pitching). Then `clize seo check --domain <d>` measures **your** site once, **in seconds**: Search Console positions for your keyword list (impression-weighted average over the window, plus the words Search Console has *not* seen yet — listed by name, at no cost), traffic by source with **AI engines listed separately**, clicks/impressions (new queries flow back into the list), the delta since the last window, and **`signals`** — the words where demand and delivery disagree, labelled (`pre_emergence` / `authority_limited` / `demand_no_surface`). **Measuring makes no upstream data calls and costs nothing**; the only metered part is pricing keywords you have never priced (~$0.10 for forty, reused for a month). For one keyword's exact position and who is ahead of you, `seo serp <keyword>` answers on demand. The research commands skip the per-call `--confirm` — the trade is that **every response opens with that call's charge in plain words** (`this call: $0.0648 (keywords, 37 words, en-US)`, and a cache hit says so and costs $0), plus `clize seo spend` — free — which itemizes every charge so the numbers in a write-up are copied, never hand-tallied. A single monthly cap guards against runaway loops and you can raise it yourself (`--cap`, $25 by default, sized so normal use never reaches it — your balance is the hard wall). The commands return **facts only**; how to read them — and where the keywords to test come from in the first place — lives in the `clize-seo` skill. See [SPEC.md](SPEC.md) U8. |
+| **SEO / GEO** (hosted data) | `clize seo keywords <seeds...>` / `competitors <domains...>` / `serp <keyword>` — research data with **no key, no signup, no upstream account**: search volume + difficulty + intent (difficulty banded by what you can actually attack), what competitors live on, and who occupies a results page (an `official_wall` / `definition_wall` / `listicle_window` / `open` verdict from a rule engine, plus the listicles worth pitching). Then `clize seo check --domain <d>` measures **your** site once, **in seconds**: Search Console positions for your keyword list (impression-weighted average over the window, plus the words Search Console has *not* seen yet — listed by name, at no cost), traffic by source with **AI engines listed separately**, clicks/impressions (new queries flow back into the list), the delta since the last window (position *and* impressions), **your pages** — impressions vs the previous window, live HTTP status and Google's index status per page, so a lost or un-indexed page shows up as a page instead of as a mysterious keyword dip — and **`signals`** — the words where demand and delivery disagree, labelled (`pre_emergence` / `authority_limited` / `demand_no_surface`). **Measuring makes no upstream data calls and costs nothing**; the only metered part is pricing keywords you have never priced (~$0.10 for forty, reused for a month). For one keyword's exact position and who is ahead of you, `seo serp <keyword>` answers on demand. The research commands skip the per-call `--confirm` — the trade is that **every response opens with that call's charge in plain words** (`this call: $0.0648 (keywords, 37 words, en-US)`, and a cache hit says so and costs $0), plus `clize seo spend` — free — which itemizes every charge so the numbers in a write-up are copied, never hand-tallied. A single monthly cap guards against runaway loops and you can raise it yourself (`--cap`, $25 by default, sized so normal use never reaches it — your balance is the hard wall). The commands return **facts only**; how to read them — and where the keywords to test come from in the first place — lives in the `clize-seo` skill. See [SPEC.md](SPEC.md) U8. |
 | **Projects** | One project = one directory: `clize init --handle <slug>` binds it (the project record auto-creates on first `claim` / `buy`). `clize projects` to list / `new` / `move` / `rename` / `rm`; `-p <slug>` for one-off cross-project calls. Email send across projects is blocked (409); deploy instead **follows the target domain** — a stale `clize.json` checkout auto-routes to the domain's real project (and is written back to `clize.json`), and only an explicit mismatched `-p` is a 409. `status` / lists / spend scope to the checked-out project, and `status` flags any local↔remote drift. |
 | **Context** | `clize status [--assets]`, `clize context [address]` — rehydrate who's waiting + identity/knowledge at the start of a session |
 | **Billing** (hosted) | `clize balance` / `clize recharge --amount <usd>` — prepaid clize balance that domain/media spends draw from (Stripe top-up); `clize audit` for the spend log |
-| **Collect** (hosted) | `clize pay link --amount <usd>` — bill *your* customers, zero config: by default money lands in your clize balance (no fee — **balance funds are spendable on clize only, not withdrawable**). Connect your own Stripe once on the web dashboard (<https://clize.ai/app#/billing>) and payments switch to your Stripe automatically (`direct`, clize takes a fee — pick this when you want cash out). Force a destination with `--mode direct\|balance`. `clize pay status` / `clize pay list`. |
-| **Shop & forms** (hosted) | `clize shop` — turn a deployed site into a storefront that takes real money: products live in a `_catalog.json` you deploy, carts check out via Stripe with **server-side pricing** against your deployed catalog (clients can't forge prices); one-time or subscriptions, shipping-address collection, `direct` or `balance` payout like `pay`. `clize shop status / orders / webhook` (orders proxy Stripe — clize stores none). `clize data webhook` forwards form / waitlist submissions to your endpoint (clize doesn't store them). Inventory, refunds, tax stay with you + Stripe — clize is the shell and payment wiring, not a Shopify. |
+| **Collect** (hosted) | `clize pay link --amount <usd>` — bill *your* customers, zero config: by default money lands in your clize balance (no fee — **balance funds are spendable on clize only, not withdrawable**). Direct payout to your own Stripe (`direct`, clize takes a fee) is **not yet enabled on the platform**; once it is, connecting Stripe on the web dashboard switches payments over automatically. Until then `--mode direct` is refused and every payment lands in your balance. `clize pay status` / `clize pay list`. |
+| **Shop & forms** (hosted) | `clize shop` — turn a deployed site into a storefront that takes real money: products live in a `_catalog.json` you deploy, carts check out via Stripe with **server-side pricing** against your deployed catalog (clients can't forge prices); one-time or subscriptions, shipping-address collection, `direct` or `balance` payout like `pay`. clize holds the order layer — `clize shop orders / todo / fulfill / notify / refund / shipments / events / webhook` (paid → sourced → shipped → delivered, 17TRACK tracking, buyer self-service at `/orders`) — while the catalog ships with your site and stock, tax and shipping stay with you. `clize data webhook` forwards form / waitlist submissions to your endpoint (clize doesn't store them). clize is the shell, the order ledger and the payment wiring, not a Shopify. |
 
 Run `clize --help` for the full surface.
 
@@ -92,7 +94,7 @@ These gates run in plain text, so every spend and every outbound action is visib
 
 ## MCP
 
-A curated subset of the core — claim, domains & DNS, email, deploy, shop & forms, status/context, billing, collect (`pay`) — exposed as **29 MCP tools** for hosts that prefer structured tools over a shell. (Media generation and the `build` method packs stay CLI- and skill-driven, not MCP tools.) Opt-in (`clize install --mcp`), since an MCP server's tool list is a standing per-session context cost — the skill alone already lets the agent drive clize via the CLI. To register by hand:
+A curated subset of the core — claim, domains & DNS, email, deploy, shop & forms, status/context, billing, collect (`pay`) — exposed as **32 MCP tools** for hosts that prefer structured tools over a shell. (Media generation and the `build` method packs stay CLI- and skill-driven, not MCP tools.) Opt-in (`clize install --mcp`), since an MCP server's tool list is a standing per-session context cost — the skill alone already lets the agent drive clize via the CLI. To register by hand:
 
 ```bash
 claude mcp add clize -- clize-mcp     # Claude Code
@@ -103,19 +105,19 @@ Works in both modes — set `CLIZE_API_KEY` (and optionally `CLIZE_API_URL`) in
 
 ### One product line at a time — `clize-mcp --profile`
 
-All 29 tools sit in context every session, even when all you wanted was the inbox. `--profile <line>` starts the same server with only that line's tools **registered** — absent from `tools/list` rather than registered-then-hidden, so the ones you skip cost the host nothing:
+All 32 tools sit in context every session, even when all you wanted was the inbox. `--profile <line>` starts the same server with only that line's tools **registered** — absent from `tools/list` rather than registered-then-hidden, so the ones you skip cost the host nothing:
 
 ```bash
-claude mcp add inbox -- clize-mcp --profile inbox      # 10 tools instead of 29
+claude mcp add inbox -- clize-mcp --profile inbox      # 13 tools instead of 32
 ```
 
-A profile only subtracts: tool names, arguments and behaviour are identical across profiles, so switching one doesn't make the agent relearn the surface. `serverInfo.name` becomes `clize-<line>` so the host shows which line is connected. Without `--profile` nothing changes — all 29 tools, `serverInfo.name` = `clize`, which is what `clize install --mcp` still registers. An unknown value exits non-zero listing the valid ones instead of quietly serving the full set (a silent fallback would hand you 29 tools while you believed you had installed a subset).
+A profile only subtracts: tool names, arguments and behaviour are identical across profiles, so switching one doesn't make the agent relearn the surface. `serverInfo.name` becomes `clize-<line>` so the host shows which line is connected. Without `--profile` nothing changes — all 32 tools, `serverInfo.name` = `clize`, which is what `clize install --mcp` still registers. An unknown value exits non-zero listing the valid ones instead of quietly serving the full set (a silent fallback would hand you 32 tools while you believed you had installed a subset).
 
 Each line is also its own npm package and MCP-registry entry, so it can be found as a product in its own right. They are metapackages around this same CLI, and the registry entries launch it with the matching profile:
 
 | Product line | `--profile` | Tools (each profile includes `status` / `balance` / `recharge`) | npm | MCP registry |
 |---|---|---|---|---|
-| **Agent Inbox** — a real inbox agents send from and receive into ([clize.ai/inbox/](https://clize.ai/inbox/)) | `inbox` | 10 — `claim`, `email setup / address add / inbox / thread / send`, `context` | `@clize/inbox` | `ai.clize/inbox` |
+| **Agent Inbox** — a real inbox agents send from and receive into ([clize.ai/inbox/](https://clize.ai/inbox/)) | `inbox` | 13 — `claim`, `email setup / address add / inbox (with wait-for) / thread / search / show / mark / send`, `context` | `@clize/inbox` | `ai.clize/inbox` |
 | **Agent Storefront** — your agent runs a real store | `storefront` | 15 — `pay`, `shop status / orders / order / todo / fulfill / notify / refund / events / shipments / webhook`, `data webhook` | `@clize/storefront` | `ai.clize/storefront` |
 | **Sites by Clize** — a marketing site that actually ships | `sites` | 5 — `claim`, `deploy` | `@clize/sites` | `ai.clize/sites` |
 | **Agent Domains** — domains an agent can buy, point and monitor | `domains` | 9 — `domain search / buy / ns`, `dns list / set / rm` | `@clize/domains` | `ai.clize/domains` |