@aisa-one/cli 0.3.0 → 0.5.1

package/CHANGELOG.md

@@ -7,6 +7,166 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.1] — 2026-09-10
+
+Compatible patch on published `0.5.0`. Browser-login-first onboarding
+guidance and an opt-in Quickstart Skill evaluation. No new commands, auth
+mechanisms, or credential-precedence changes.
+
+### Changed
+
+- README, missing-key errors, `whoami`, and Router help recommend `aisa login`
+  (browser; stores a CLI key) before pasting a key. `AISA_API_KEY` and
+  `aisa login --key` remain for CI. Resolution order is unchanged:
+  `AISA_API_KEY`, then `~/.aisa/key`, then legacy login.
+- Quick Start covers login, discovery, catalog browse, and quote. It does not
+  copy `aisa chat` or `aisa call`. Quote is a price observation; approval and
+  whether to execute remain caller-owned guidance, not an enforced CLI gate.
+
+### Added
+
+- Default-off `eval/agent-quickstart/` Skill ablation. Reuses the existing
+  Router stub and pack path. Excluded from the npm package; does not run in
+  default CI or against production AIsa credentials.
+
+## [0.5.0] — 2026-09-09
+
+PR21 command-surface cleanup. Published to npm as `0.5.0`. Distinct from the
+unpublished `0.4.0` main baseline (`0.4.0` was never tagged or published).
+
+### Breaking
+
+- **Domain shortcuts and raw execution are removed.** These names are
+  unknown commands — not aliases and not auto-forwarded to `aisa call`:
+  `web-search`, `scholar`, `stock`, `crypto`, `screener`, `tweet`, `twitter`
+  (all children), `video` (all children), `run`, top-level `code`,
+  `api search`, and `api code`. Root help is 22 entries including implicit
+  `help` (21 explicit commands).
+- **`aisa api list` and `aisa api show` stay** as the supported read-only
+  provider/endpoint catalog. They are not deprecated and are not a
+  substitute for `schema` / `quote`. Catalog paths and prices are browsing
+  metadata. `api show` is not equivalent to `aisa schema`. The `0.4.0`
+  deprecation of `api show` is withdrawn because the command is retained.
+
+### Changed
+
+- Bundled `aisa skills init` templates may keep domain labels (`search`,
+  `finance`, `twitter`, `video`). Runnable steps use `search` / `schema` /
+  `quote` / `call` and optional `api list` / `api show`. They do not invent
+  tool names or treat Router as covering every removed domain function. The
+  `llm` template stays on `chat` / `models`.
+- Root and Router help/manifest no longer document removed names. Router
+  `mcp` / `auth` / `exits` / `examples` still attach only to top-level
+  `search` / `schema` / `quote` / `call`, not nested `skills search`.
+
+## [0.4.0] — unpublished main baseline
+
+Unpublished `main` candidate as of 2026-09-08. Not tagged and not on npm
+(skipped between `0.3.0` and published `0.5.0`). Kept so the Router work and the
+`api search` / `api show` / `run` deprecation history stay identifiable.
+
+### Breaking
+
+- **`aisa search` is no longer an alias for `api search`.** It now calls the
+  Tool Router (`POST /v1/tool-router/aisa-search-tool`) and prints Router
+  results. The old catalog keyword search remains as `aisa api search`.
+
+### Added
+
+- **`aisa search` / `schema` / `quote` / `call`** — Unix-oriented entries for
+  the same four Router operations as MCP. Accept `--input '<json>'` and
+  `-f/--file` (including `-f -` for stdin). `--json` writes the unmodified
+  application response, including integer tokens outside JavaScript's safe
+  range. Quote never executes; none of the four retry or fall back to
+  provider shortcuts. Router origin is `AISA_ROUTER_BASE_URL`, else config
+  `routerUrl`, else `https://tools.aisa.one`. The LLM/catalog host
+  `https://api.aisa.one` is unchanged and is not a Router fallback.
+
+### Fixed
+
+- Router `search` / `schema` / `quote` / `call` do not follow HTTP redirects.
+  A 307/308 is a transport failure, so a quote response cannot become a use.
+- Human quote/call print each result's own micro-USD token, including values
+  above 2^53. `--json` was already lossless.
+- Full `--input` / `-f` envelopes reject unknown fields, duplicate `call_id`,
+  and non-unique or oversized `provider_filters` before dispatch.
+- Human search prints a returned `plan` (`plan_ref`, steps, pitfalls) when
+  the Router includes one.
+- Default Tool Router origin is `https://tools.aisa.one`. Anonymous
+  `/v1/tool-router/...` on `api.aisa.one` returns 404; the deployed nginx
+  front door is `tools.aisa.one`. Overrides (`AISA_ROUTER_BASE_URL`,
+  `routerUrl`) keep precedence. There is no origin fallback.
+
+### Changed
+
+- Human Router guidance and displayed plan steps/pitfalls project the four
+  exact MCP identifiers onto `aisa search` / `schema` / `quote` / `call`.
+  Surrounding policy text is unchanged. `--json` still prints the unmodified
+  application body, including MCP identifiers.
+- Root and Router command help include complete `--input` JSON examples
+  (`-f` / `-f -` too), configured-key resolution shared with `run`
+  (`AISA_API_KEY`, then `~/.aisa/key`, then legacy login), billable/approval
+  limits, and exits `0`/`2`/`1`/`3`. Manifest nodes for the four commands
+  include `mcp`, `auth`, `safety`, `exits`, and parseable `examples`; the
+  root node includes `router`. Shell `--input` examples use POSIX single
+  quotes. Help separates enforced key/input checks from caller instructions;
+  the CLI does not reject an unquoted call. Router `mcp` / `auth` / `exits` /
+  `examples` attach only to top-level `search` / `schema` / `quote` / `call`,
+  not nested `api search` / `twitter search` / `skills search`.
+
+### Deprecated
+
+- **`aisa api search`, `aisa api show`, and `aisa run`** keep their previous
+  behavior, stdout, and exit semantics. Help, one stderr warning, and
+  manifest `deprecated` / `replacement` / `migration` fields mark them as
+  not drop-in replacements. `api list`, `api code`, and specialized commands
+  are unchanged. Removal will be a separately announced breaking release.
+
+### Added
+
+- **`aisa connect`** — a one-shot local page (`npx @aisa-one/cli connect`) to
+  wire AIsa MCP servers into local coding agents. Detects Claude Code, Cursor,
+  Claude Desktop and Windsurf; Claude Code entries go through `claude mcp add`
+  (user scope), the rest through the same config writer as `mcp setup`. The
+  process serves one token-guarded page on 127.0.0.1, applies the selection,
+  drives the sign-in, and exits — no daemon left behind. With no key stored,
+  the run starts with one browser approval (the same flow as `aisa login`)
+  that mints the durable CLI key; every MCP entry and the model provider are
+  then written with it — no per-server authorization popups. Only if that
+  sign-in fails does connect fall back to each client's own OAuth machinery
+  (`claude mcp login` per server; `codex mcp add` runs its own flow). A
+  configured key skips the sign-in entirely.
+  The page follows the AIsa Console design (warm dot-grid, Inter, the
+  Console red), groups servers by category with their manifest descriptions,
+  shows per-server authorization progress live, and finishes by opening a
+  success page with copy-paste example prompts that name each `aisa-*`
+  server explicitly so the request routes to AIsa.
+- **`aisa topup [amount]`** — opens the console billing page to add credit,
+  deep-linking `?amount=` when one is given and rejecting anything that is not
+  a positive number of dollars. Payment finishes in the browser by necessity
+  (Stripe's hosted page owns the card details; 3-D Secure needs a browser).
+  `aisa balance` now points at it when the account is out of credit.
+- **`aisa login` signs in over OAuth and keeps a real key.** With no
+  arguments it opens the browser for one approval, then trades the access
+  token for the long-lived CLI key at `POST /v1/keys/mint` and stores only
+  the key. `--no-browser` prints the URL and reads the redirect back for
+  headless machines; `--key <key>` still stores one directly.
+- **Codex MCP entries carry the key itself, not an env-var name.**
+  `codex mcp add --bearer-token-env-var` records only a variable name that
+  nothing guarantees a shell exports, so keyed entries could 401 at runtime.
+  After the add (which the flag keeps free of OAuth popups), the entry is
+  patched to a literal `http_headers` Authorization — the same thing the
+  Claude Code path stores via `--header`.
+- The npm tarball includes the MIT `LICENSE` text (Copyright (c) 2026
+  AIsa Team). License policy is unchanged.
+- CI on every push/PR builds, tests, and pack-smokes on Ubuntu Node
+  18/20 (legacy compatibility), 22/24 (maintained), and 26 (current).
+  `engines` stay `>=18`.
+  The tag-triggered publish job uses Node 24. Trusted Publisher on npmjs.com
+  is a publish-time prerequisite — this repo has no historical `release.yml`
+  success. `prepack` builds the tarball so a clean `npm pack` includes
+  `dist` and `LICENSE`. `git push origin vX.Y.Z` is the publish button.
+
 ## [0.3.0] — 2026-08-18
 
 ### Fixed
@@ -246,7 +406,11 @@ supports today; nothing here depends on a backend change.
 - Config commands (`aisa config get|set|list|reset`) and auth
   (`aisa login|logout|whoami`).
 
-[Unreleased]: https://github.com/AIsa-team/cli/compare/v0.2.4...HEAD
+[Unreleased]: https://github.com/AIsa-team/cli/compare/v0.5.1...HEAD
+[0.5.1]: https://github.com/AIsa-team/cli/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/AIsa-team/cli/compare/v0.3.0...v0.5.0
+[0.4.0]: https://github.com/AIsa-team/cli/compare/v0.3.0...b5c0b04b2a7a2cb9efcb568be5ee5440d7f7d94d
+[0.3.0]: https://github.com/AIsa-team/cli/compare/v0.2.4...v0.3.0
 [0.2.4]: https://github.com/AIsa-team/cli/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/AIsa-team/cli/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/AIsa-team/cli/compare/v0.2.1...v0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AIsa Team
+
+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.

package/README.md

@@ -1,8 +1,9 @@
 # @aisa-one/cli
 
-Command-line access to [AIsa](https://aisa.one): **one API key for 80+ LLMs and
-950+ endpoints** across 29 API providers — finance, web search, social,
-research, and video generation.
+Command-line access to [AIsa](https://aisa.one): **one API key** for
+**Claude, GPT, Gemini, DeepSeek, Kimi, GLM** and published Tool Router
+operations. Browse the public provider/endpoint catalog separately;
+catalog metadata is not a substitute for `schema` or `quote`.
 
 ## Install
 
@@ -13,84 +14,137 @@ npm install -g @aisa-one/cli
 ## Quick Start
 
 ```bash
-# Authenticate (or set AISA_API_KEY)
-aisa login --key sk-your-api-key
+# Sign in (browser; stores a CLI key — no key to copy)
+aisa login
 
-# See what's available — no API key needed for this part
-aisa api list
-aisa api search "insider trades"
-
-# Chat with any model
-aisa chat "Explain quantum computing" --model claude-opus-4-6
+# Discover published tools (Router; search/schema may be anonymous)
+aisa search "company facts" --json
+aisa schema get_financial_company_facts --json
 
-# Look up a stock
-aisa stock AAPL
+# Browse the read-only provider/endpoint catalog
+aisa api list
+aisa api show financial
 
-# Search the web
-aisa web-search "latest AI research"
+# Quote a published Router tool (does not execute)
+aisa quote --input '{"calls":[{"call_id":"c1","tool":"get_financial_company_facts","arguments":{"ticker":"AAPL"}}]}' --json
+```
 
-# Call any endpoint in the catalog directly
-aisa run financial /insider-trades -q "ticker=AAPL"
+`aisa login` opens a browser, signs you in, and stores a CLI key. You do not
+need to create or paste a key from the console. For CI or scripts, set
+`AISA_API_KEY` or run `aisa login --key <key>`. New accounts receive $5 in
+free credits.
+
+This first block does not run `aisa chat` or `aisa call`. Quote is a price
+observation, not authorization to execute. See
+[Published tools](#published-tools-tool-router) for the quote/approval
+contract before a billable call.
+
+Root help lists 21 explicit commands plus implicit `help`. Removed domain
+shortcuts and raw execution names are unknown commands — not aliases and
+not forwarded to `aisa call`.
+
+## Published tools (Tool Router)
+
+These four commands are a thin HTTP client for the same Router service MCP
+uses. They do not search the local catalog cache and do not call providers
+directly.
+
+| CLI | MCP identifier | POST path |
+|---|---|---|
+| `aisa search` | `AISA_SEARCH_TOOL` | `/v1/tool-router/aisa-search-tool` |
+| `aisa schema` | `AISA_BATCH_GET_SCHEMA` | `/v1/tool-router/aisa-batch-get-schema` |
+| `aisa quote` | `AISA_BATCH_QUOTE` | `/v1/tool-router/aisa-batch-quote` |
+| `aisa call` | `AISA_BATCH_USE` | `/v1/tool-router/aisa-batch-use` |
+
+`--json` prints the unmodified application body (MCP identifiers stay).
+Human output maps only those four identifiers onto CLI names. `aisa manifest`
+and `aisa manifest search` / `schema` / `quote` / `call` expose `mcp`, `auth`,
+`enforced`, `safety`, `exits`, and parseable `examples`.
+
+Recommended sequence: discover a tool → `aisa schema` when
+`has_full_schema=false` → `aisa quote` → `aisa call`. Quote and call share
+one request shape. **Enforced:** invalid local input exits 2 and is not sent;
+quote and call refuse to run without a configured AIsa API key. **Not
+enforced:** the CLI does not record quotes, approvals, or budget caps and
+does not reject an unquoted call. **Instruction:** do not execute unquoted
+calls; the caller must ensure a matching quote and approval. Quote is a
+price observation, not authorization. A data request or credentials alone is
+not spending approval. Do not invent tool names or guess required values.
+`aisa call` is billable. A missing or failed quote is never free. Estimated
+cost is not a limit. If a hard monetary cap is required, do not execute
+calls with no guaranteed maximum. A partial quote is not a full-batch total;
+call only an independently approved successful subset, and do not silently
+retry. Without a configured AIsa API key, do not invent a business result.
+
+`--input` is inline JSON (no file required). Documented shell examples use
+POSIX single quotes so apostrophes, Unicode, `$()`, and backticks stay
+literal.
+
+`get_financial_company_facts` is a published tool whose schema includes
+`ticker`. Do not invent unpublished tool names. Router search does not
+guarantee every former domain-shortcut function.
+
+```sh
+aisa search "company facts" --json
+aisa search --input '{"query":"company facts","limit":5}' --json
+aisa search --input '{"query":"company facts","known_fields":{"name":"O'\''Reilly — 苹果"}}' --json
+aisa search -f request.json --json
+aisa search -f - --json < request.json
+aisa schema get_financial_company_facts --json
+aisa schema --input '{"tools":["get_financial_company_facts"]}' --json
+aisa quote --input '{"calls":[{"call_id":"c1","tool":"get_financial_company_facts","arguments":{"ticker":"AAPL"}}]}' --json
+aisa quote -f request.json --json
+aisa call --input '{"calls":[{"call_id":"c1","tool":"get_financial_company_facts","arguments":{"ticker":"AAPL"}}]}' --json
+aisa call -f - --json < request.json
 ```
 
-Get your API key at
-[console.aisa.one/api-keys](https://console.aisa.one/api-keys). New accounts
-receive $5 in free credits.
+`--json` keeps large integer tokens. Diagnostics go to stderr. Exit `2` means
+local input was invalid and nothing was sent; `1` is transport, auth, or an
+HTTP error; `3` means the Router returned a batch with at least one failed
+item.
+
+`search` and `schema` may be anonymous. `quote` and `call` require a
+configured AIsa API key. Sign in with `aisa login` first; it mints and stores
+a CLI key. Resolution order is unchanged: `AISA_API_KEY`, then `~/.aisa/key`,
+then legacy login. `AISA_API_KEY` still takes precedence over the stored key.
+For CI, set `AISA_API_KEY` or use `aisa login --key <key>`. The default Router
+origin is `https://tools.aisa.one` (independent of `baseUrl` /
+`https://api.aisa.one`). Point a test Router at `AISA_ROUTER_BASE_URL` (origin
+or prefix before `/v1/tool-router/...`), or `aisa config set routerUrl`. There
+is no origin fallback.
+
+`quote` never executes. Router requests do not follow HTTP redirects, so a
+307/308 cannot turn quote into call. There is no automatic quote-to-call sequence and no
+retry.
 
 ## API Catalog
 
-The catalog is the fastest way to find what the platform can do. It reads a
-public endpoint, so `list`, `show`, `search`, and `code` all work before you log
-in.
+`api list` and `api show` are the supported read-only catalog. They browse
+public provider and endpoint metadata (`--json`, `--refresh`, `--health`,
+`--category`, path filters). They are not deprecated and are not Router
+`search` / `schema`. Catalog paths and prices are browsing metadata, not a
+substitute for schema or quote, and not a way to execute an endpoint.
 
 ```bash
-aisa api list                          # all 29 providers
+aisa api list                          # all catalog providers
 aisa api list --category finance       # finance, search, social, productivity, other
 aisa api list --health                 # include provider health
 
-aisa api show financial                # every endpoint in one provider
-aisa api show financial /news          # one endpoint: params, price, run command
-aisa api show dataforseo --all         # 453 endpoints (truncated to 40 by default)
-
-aisa api search "stock screener"       # search across all 950+ endpoints
-aisa api search rank --provider dataforseo
-
-aisa api code financial /news --lang curl     # curl, python, node, typescript
+aisa api show financial                # endpoints in one provider
+aisa api show financial /news          # one endpoint: params and catalog price
+aisa api show dataforseo --all         # long lists truncate to 40 by default
 ```
 
-Two things worth knowing: a provider's **id is not always its URL slug** —
-`brave-search` serves `/apis/v1/brave/...`, and `api show` prints the path you
-actually call. And the catalog reports every method as `GET`; pass `--method` to
-`api code` when an endpoint takes a POST.
+A provider **id is not always its URL slug** — `brave-search` serves
+`/apis/v1/brave/...`, and `api show` prints the catalog path. The catalog
+reports every method as `GET`; treat that as advisory.
 
 The catalog is cached in `~/.aisa/cache` (override with `AISA_CACHE_DIR`). Pass
 `--refresh` to any command to bypass it, or `aisa cache clear`.
 
-## Execute Any Endpoint
-
-```bash
-aisa run financial /insider-trades -q "ticker=AAPL"
-aisa run coingecko /simple/price -q "ids=bitcoin&vs_currencies=usd"
-aisa run brave /web/search -q "q=AI agents"
-aisa run tavily /search -d '{"query": "AI news"}'
-aisa run twitter /tweet/advanced_search -q "query=AI agents" --raw
-aisa run dataforseo /serp/google/organic/live -d '{...}' --show-cost
-```
-
-`run` sends anything that isn't a known LLM gateway route to the integration
-APIs, so providers added to the platform work without a CLI upgrade. Use
-`--llm` or `--domain` to force a base.
-
-`--show-cost` prints the gateway's billing headers on stderr, so it stays out of
-the way of `--raw | jq`. Metered providers (DataForSEO, Jina) report the amount
-actually charged and the credits consumed — for those the catalog's flat
-per-request price is not what you pay. Other routes report only a price key, and
-the LLM gateway reports nothing; the output says so rather than implying a call
-was free.
-
 ## LLM Gateway
 
-80+ models (GPT, Claude, Gemini, Qwen, Deepseek, Grok) behind one
+GPT, Claude, Gemini, DeepSeek, Kimi, GLM, Qwen and the rest behind one
 OpenAI-compatible endpoint.
 
 ```bash
@@ -106,91 +160,19 @@ aisa models show gpt-4.1-mini        # model details
 
 Streaming is on by default; pass `--no-stream` to disable it.
 
-## Finance
-
-```bash
-aisa stock AAPL                     # summary: company info + estimates + news
-aisa stock AAPL --field insider     # insider trades
-aisa stock AAPL --field news        # company news
-aisa stock TSLA --field filings     # SEC filings
-aisa stock MSFT --field estimates   # analyst EPS & revenue estimates
-aisa stock AAPL --field financials  # balance sheets, income statements
-
-aisa crypto BTC                     # price, 24h change, market cap
-aisa crypto ETH --period 30d        # historical
-aisa crypto --id render-token RNDR  # exact CoinGecko id when a symbol is ambiguous
-
-aisa screener --sector "Information Technology"
-aisa screener --min-market-cap 1000000000000 --limit 10
-aisa screener --filter market_cap:gt:1e12 --filter sector:eq:Financials
-```
-
-Sectors use GICS names; short forms like `Technology` are mapped automatically.
-
-## Web Search
-
-```bash
-aisa web-search "query"                     # Tavily (default)
-aisa web-search "query" --type youtube      # YouTube search
-aisa scholar "transformer architecture"     # academic papers
-```
-
-`--type smart` and `--type full` are currently degraded upstream and return 404
-regardless of parameters. Use `tavily` until that is resolved.
-
-## Twitter/X
-
-```bash
-aisa twitter user elonmusk                  # user profile
-aisa twitter search "AI agents" --limit 20  # search tweets
-aisa twitter trends                         # trending topics
-aisa twitter user-tweets elonmusk           # recent tweets
-aisa twitter thread <tweet-id>              # full conversation
-```
-
-Read operations work with just your API key. **Write operations** (`aisa tweet`,
-`like`, `retweet`, `follow`, `dm`) additionally require Twitter login cookies
-and a proxy — run `aisa twitter login --username <u> --password <p> --proxy <url>`
-first. Run `aisa twitter --help` for the full list of 30+ subcommands.
-
-## Video Generation
-
-```bash
-aisa video create "A sunset timelapse"                  # returns a task id
-aisa video create "Dancing robot" --wait                # poll until done
-aisa video create "A cat" --output cat.mp4              # wait and download
-aisa video status <task-id>
-
-# image-to-video: --image is shorthand for --media first_frame=<url>
-aisa video create "the bird turns its head" --model wan2.7-i2v --image https://…/photo.jpg
-aisa video create "extend this clip" --model wan2.7-r2v --media first_clip=https://…/in.mp4
-
-# Seedance uses a different request shape; the CLI handles it
-aisa video create "a cat walking" --model dreamina-seedance-2-0-fast-260128
-```
-
-| Model | Needs | Billing |
-|-------|-------|---------|
-| `wan2.7-t2v` (default), `happyhorse-1.1-t2v` | prompt only | per second |
-| `wan2.7-i2v`, `happyhorse-1.1-i2v` | `--image` / `--media first_frame=` | per second |
-| `wan2.7-r2v`, `happyhorse-1.1-r2v` | `--media first_clip=` | per second |
-| `dreamina-seedance-2-0-260128`, `…-fast-260128` | prompt only | per token |
-
-Media types: `first_frame`, `last_frame`, `driving_audio`, `first_clip`.
-
-The gateway forwards the request body to whichever vendor owns the model, so the
-shape differs per family — the CLI builds it for you and refuses up front if a
-model needs source media you did not supply (the upstream would otherwise accept
-the job, bill it, and fail a minute later). For a vendor or parameter the CLI
-does not model, `--body '<json>'` is sent verbatim.
-
 ## Account
 
 ```bash
 aisa balance                        # wallet and API key credit balance
 aisa balance --json
+aisa topup                          # open the console billing page to add credit
+aisa topup 20                       # same, deep-linked to $20
 ```
 
+Payment always finishes in the browser: card details belong to Stripe's hosted
+page, not to us, and a bank's 3-D Secure step needs one. `topup` opens the
+right page; `--no-open` prints the URL instead.
+
 `aisa usage` is not available yet — the gateway does not serve
 `GET /v1/credits/usage` (it 404s, while `/v1/credits/balance` on the same route
 group works). Use the [console](https://console.aisa.one/logs) for usage history
@@ -199,9 +181,8 @@ in the meantime.
 ## Skills
 
 Skills are markdown files that teach AI coding agents (Claude Code, Cursor,
-Copilot, …) how to use AIsa APIs. They come from the
-[agent-skills](https://github.com/AIsa-team/agent-skills) repository — 42 skills
-across six categories.
+Copilot, …) how to use AIsa. They come from the
+[agent-skills](https://github.com/AIsa-team/agent-skills) repository.
 
 ```bash
 aisa skills list                              # all skills
@@ -244,11 +225,37 @@ aisa skills init my-skill                          # default template
 aisa skills init my-skill --template finance       # finance, llm, search, twitter, video
 ```
 
+Bundled templates may keep those domain labels. Their runnable steps use
+`search` / `schema` / `quote` / `call` (and optional `api list` / `api show`).
+They do not invent tool names or treat Router as a replacement for every
+removed shortcut. The `llm` template stays on `chat` / `models`.
+
 To publish a skill, open a pull request against
 [AIsa-team/agent-skills](https://github.com/AIsa-team/agent-skills).
 
 ## MCP Server
 
+### One-liner: `connect`
+
+```bash
+npx @aisa-one/cli connect
+```
+
+Opens a small local page (served by this process on `127.0.0.1`, shut down
+when finished) where you tick the AIsa MCP servers you want and the coding
+agents to install them into. Claude Code is configured through its own
+`claude mcp add` (user scope), then signed in through its own OAuth: connect
+runs `claude mcp login` per server, your browser opens the AIsa
+authorization, and the tokens live in Claude Code's own store where it also
+refreshes them — no API key, nothing pasted. Cursor, Claude Desktop and
+Windsurf get config entries and run the same OAuth themselves on first use.
+The page matches the AIsa Console style, reports authorization progress
+live, and a success page with copy-paste try-it-now prompts opens when
+everything is connected. No daemon stays behind. `--no-open` prints the URL
+instead of launching a browser; `--dry-run` shows what would be written.
+
+### Scripted: `mcp setup`
+
 ```bash
 aisa mcp setup                          # configure the default servers for every detected client
 aisa mcp setup --all                    # every live server, not just the defaults
@@ -288,12 +295,10 @@ Completion covers commands, subcommands, and options, plus values pulled from
 the local cache:
 
 ```
-aisa run <TAB>                 → 29 provider slugs
-aisa run financial <TAB>       → that provider's endpoints
 aisa api show <TAB>            → provider ids
-aisa skills show <TAB>         → 42 skill names
+aisa api list --category <TAB> → finance, search, social, productivity, other
+aisa skills show <TAB>         → skill names
 aisa chat --model <TAB>        → model ids
-aisa web-search --type <TAB>   → tavily, youtube, scholar, …
 ```
 
 The cache-backed suggestions only appear once the relevant command has been run
@@ -314,11 +319,16 @@ Settings:
 - `defaultModel` — default model for `aisa chat` (default: `gpt-4.1-mini`)
 - `baseUrl` — platform root; the LLM (`/v1`), integration (`/apis/v1`), and
   catalog bases are all derived from it
+- `routerUrl` — Tool Router origin (default `https://tools.aisa.one`,
+  independent of `baseUrl`); overridden by `AISA_ROUTER_BASE_URL`
 - `outputFormat` — `text` or `json`
 
-Environment variables: `AISA_API_KEY` takes precedence over the stored key.
-`AISA_CACHE_DIR` relocates the cache. `GITHUB_TOKEN` raises the GitHub rate
-limit for skills commands.
+`aisa login` stores a CLI key in `~/.aisa/key`. Environment variables:
+`AISA_API_KEY` takes precedence over the stored key.
+`AISA_ROUTER_BASE_URL` is the Router origin/prefix before
+`/v1/tool-router/...` and overrides the default `https://tools.aisa.one`.
+`AISA_CACHE_DIR` relocates the cache. `GITHUB_TOKEN`
+raises the GitHub rate limit for skills commands.
 
 ## Development
 
@@ -329,8 +339,12 @@ npm install
 npm run build       # compile TypeScript
 npm run dev         # watch mode
 npm test            # run tests
+npm run package:smoke  # clean pack, isolated install, installed-bin checks
 ```
 
+Release metadata and the exact merge/tag publish path (not an authorization
+to publish) are in [`docs/release.md`](docs/release.md).
+
 ## Appendix: Notes for Contributors
 
 **Three bases, one root.** `resolveBases()` in `src/api.ts` derives the LLM base
@@ -339,12 +353,6 @@ configured `baseUrl`. It tolerates a value with either suffix already attached,
 because the shipped default has always included `/v1` and is persisted in every
 existing user's config.
 
-**Routing in `run`.** `resolveRunTarget()` (`src/commands/run.ts`) treats the LLM
-gateway routes as the whitelist and everything else as an integration API. That
-direction matters: gateway routes are hardcoded server-side and change roughly
-annually, while provider slugs are database rows that operations edit
-continuously.
-
 **The catalog's shape has three traps.** `endpoints[].method` is hardcoded to
 `GET` server-side. `endpoint_groups[].name` is an operator-entered label
 (`Zero`, `One`, `default`) with no business meaning, which is why `api show`
@@ -353,23 +361,9 @@ per-endpoint counts are one value repeated.
 
 **Parameter naming varies by endpoint.** Scholar uses `query`, finance uses
 `ticker` (not `symbol`), Twitter uses `userName`. `aisa api show <api> <path>`
-prints each endpoint's description and path parameters.
-
-**Video generation is async.** `POST /v1/video/generations` returns `202` with a
-gateway-local `video_task_<hex>` id. Poll `GET /v1/video/generations/:id` until
-`status` is one of `completed`, `failed`, or `cancelled`. The finished URL sits
-at a different place in `result` for each vendor, so `findVideoUrl()` searches
-for it.
-
-**Twitter write operations require login cookies.** `create_tweet_v2` and the
-other action endpoints need `login_cookies` and `proxy` in the body — the
-gateway does not hold your Twitter session.
-
-**Some financial endpoints return empty data.** `financial/prices` and
-`financial/financial-metrics/snapshot` return `{}` for all tickers. `aisa stock`
-uses `company/facts` + `analyst-estimates` + `news` instead. Working fields:
-`info`, `estimates`, `financials`, `filings`, `insider`, `institutional`, `news`.
+prints each endpoint's description and path parameters. That listing is
+catalog metadata, not an execution recipe.
 
 ## License
 
-MIT
+MIT. See [LICENSE](LICENSE). Copyright (c) 2026 AIsa Team.

package/dist/api.d.ts

@@ -33,6 +33,16 @@ export interface RequestOptions {
     headers?: Record<string, string>;
     /** Use domain API base URL (/apis/v1) instead of LLM base (/v1) */
     domain?: boolean;
+    /**
+     * Safe to send more than once, so a transient failure can be retried.
+     * Must be set deliberately: this CLI POSTs for reads and for writes alike,
+     * and a retried write posts a second tweet or bills a second video job.
+     * See utils/http.ts for why `chat` stays out of this even though a
+     * completion reads rather than writes.
+     */
+    idempotent?: boolean;
+    /** Overrides the default 30s budget for a slow endpoint. */
+    timeoutMs?: number;
 }
 export declare function apiRequest<T = unknown>(apiKey: string, endpoint: string, options?: RequestOptions): Promise<ApiResponse<T>>;
 export declare function apiRequestRaw(apiKey: string, endpoint: string, options?: RequestOptions): Promise<Response>;