docs: pin canonical AIsa skill.md and current credential guidance

.github/workflows/check-canonical-skill.yml

@@ -0,0 +1,30 @@
+name: Check canonical AIsa skill
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Pinned export check
+        run: python3 scripts/sync_canonical_aisa_skill.py --check
+      - name: Reject mutated export
+        run: |
+          tmp=$(mktemp -d)
+          cp skill.md "$tmp/skill.md"
+          printf '\nmutated\n' >> "$tmp/skill.md"
+          if python3 scripts/sync_canonical_aisa_skill.py --check --root "$tmp"; then
+            echo "::error::--check accepted a mutated skill.md"
+            exit 1
+          fi

agent-quickstart-fallbacks.mdx

@@ -7,13 +7,13 @@ Do not use this page as the default setup. Return to [Agent Quickstart](https://
 
 ## Skill download (curl)
 
-**Gate:** Node or `npx skills` cannot run, you need the official `aisa` skill on disk, and either this is a user-local machine **or** the user explicitly prefers CLI/Skill in this environment (including a cloud sandbox). Download the complete three files (`SKILL.md`, `LICENSE`, `agents/openai.yaml`) into this client's native Skill location. Preserve an existing official or custom skill, including a symlink; do not claim Web persistence without a native install. Codex user-level example: `~/.agents/skills/aisa`. The primary installer remains Node.js **22.20.0+** and `skills` 1.5.25 `engines`; this curl path does not change those floors.
+**Gate:** Node or `npx skills` cannot run, you need the official `aisa` skill on disk, and either this is a user-local machine **or** the user explicitly prefers CLI/Skill in this environment (including a cloud sandbox). Download the complete three files (`SKILL.md`, `LICENSE`, `agents/openai.yaml`) into this client's native Skill location. Preserve an existing official or custom skill, including a symlink; do not claim Web persistence without a native install. Codex user-level example: `~/.agents/skills/aisa`. The primary installer remains Node.js **22.20.0+** and `skills` 1.5.25 `engines`; this curl path does not change those floors. The raw GitHub pin is Skill commit `e7809490a186af77c4b96a5c1cfeea1ee39ce4f9`.
 
 ```sh
 set -e
 aisa_skill_target="$HOME/.agents/skills/aisa"
 aisa_skill_parent="$HOME/.agents/skills"
-aisa_skill_base="https://raw.githubusercontent.com/AIsa-team/agent-skills/7d7b1267f4363d894528f5c5b8d895214211cb84/platform/aisa"
+aisa_skill_base="https://raw.githubusercontent.com/AIsa-team/agent-skills/e7809490a186af77c4b96a5c1cfeea1ee39ce4f9/platform/aisa"
 if [ -e "$aisa_skill_target" ] || [ -L "$aisa_skill_target" ]; then
   echo "exists, left unchanged: $aisa_skill_target"
   echo "not assumed official; inspect before treating as the AIsa skill"
@@ -30,9 +30,9 @@ mv "$aisa_skill_tmp/aisa" "$aisa_skill_target"
 
 ## Direct HTTP API fallback
 
-**Gate:** CLI and MCP are both unavailable, HTTP requests are supported, and a valid existing AIsa API key or secret is already available. Read this entire section — endpoint docs, pricing, and the approval XML — before presenting a paid proposal or cost approval, and before any paid request.
+**Gate:** The CLI is not usable here, MCP is unavailable, HTTP requests are supported, and a static `AISA_API_KEY` or equivalent secret is already configured in this environment. If the CLI is usable, leave this page and follow the CLI path on [Agent Quickstart](https://aisa.one/docs/agent-quickstart.md). Read this entire section — endpoint docs, pricing, and the approval XML — before presenting a paid proposal or cost approval, and before any paid request.
 
-Use this only when CLI and MCP are both unavailable, HTTP requests are supported, and a valid existing AIsa API key or secret is already available. Use this for a client, tooling, or router limitation; it does not bypass invalid API credentials, exhausted credit, or a failure of the same underlying API.
+Use this only for a client, tooling, or router limitation that blocks CLI and MCP. It does not bypass invalid API credentials, exhausted credit, or a failure of the same underlying API.
 
 Use the matching endpoint reference and published pricing. [API Reference](https://aisa.one/docs/api-reference). [Authentication](https://aisa.one/docs/guides/authentication). Data APIs: `https://api.aisa.one/apis/v1`. Model catalog: `https://api.aisa.one/v1/models`. Read [pricing](https://aisa.one/docs/guides/pricing) before any paid data request.
 
@@ -42,11 +42,9 @@ Send the key as a Bearer token. Do not send a paid example request from this pag
 
 ### API key
 
-Reuse `AISA_API_KEY`. If it is unset and this agent can read the filesystem, use `~/.aisa/key` from `aisa login` without displaying it. Otherwise use an AIsa API key already in this client's authorized secret store. If sources conflict, explain them; do not overwrite a custom key.
+Direct HTTP requires a separately configured static `AISA_API_KEY` or equivalent secret already present as an environment variable or in this client's authorized secret store. Browser `aisa login` and other OAuth flows do not manufacture a static HTTP key. Do not run `aisa login` from this fallback. Do not read `tokens.json` or compatibility key files. If sources conflict, explain them; do not overwrite a custom key.
 
-If none of those exist and `aisa login` is usable, run browser `aisa login` so the key is stored automatically. If there is no usable CLI or browser-login path, the last option is for the user to sign in at https://console.aisa.one/api-keys, create a key, and save it in this client's credential or secret settings, or as local `AISA_API_KEY`. Do not ask them to paste the key into chat. Do not print it. Not every client has a secret UI; if this client cannot store a credential, stop there.
-
-Wait for credentials before protected API requests. Obtaining a key is not paid-call approval.
+If no static key or secret is already configured, stop. Do not ask the user to paste a key into chat. Do not print it. Do not send the user to copy a dashboard key into this conversation. Obtaining a key is not paid-call approval.
 
 ## Paid API approval first
 

agent-quickstart.mdx

@@ -27,7 +27,7 @@ npm install -g @aisa-one/cli
 aisa --version
 ```
 
-Reuse `@aisa-one/cli` **0.5.0 or later** if present; otherwise install; do not downgrade. CLI may keep Node.js **18+**. Read the on-disk skill. Sign in via that skill and `aisa login --help`. Prove auth with `aisa balance`. `aisa whoami` is local only. `AISA_API_KEY` overrides the stored key; if they conflict, explain both. Never print credentials or send the user to copy a dashboard key. Browser `aisa login` is the primary credential path.
+Reuse `@aisa-one/cli` **0.5.0 or later** if present; otherwise install; do not downgrade. CLI may keep Node.js **18+**. Read the on-disk skill. Sign in via that skill and `aisa login --help`. Prove auth with `aisa balance`. `aisa whoami` may refresh stored tokens and is not protected auth proof. `AISA_API_KEY` overrides stored CLI credentials and never refreshes; if they conflict, explain both. Never print credentials, read token files, or send the user to copy a dashboard key. Browser `aisa login` is the primary credential path.
 
 ## Cloud
 
@@ -43,4 +43,4 @@ Then those four tools: search → schema when `has_full_schema` is false → quo
 
 Do not jump to HTTP to bypass missing credentials, exhausted credit, or the same API outage. Do not make paid calls to test availability. Do not extract client-owned MCP OAuth tokens.
 
-Only if CLI and MCP are both unavailable, HTTP works, and a valid AIsa key already exists: read the full direct HTTP section of [Agent Quickstart fallbacks](https://aisa.one/docs/agent-quickstart-fallbacks.md) (endpoint docs, pricing, approval XML) before a paid proposal, cost approval, or paid request. Extra models, REST, keys, or skills: [AIsa docs](https://aisa.one/docs).
+Only if the CLI is not usable, MCP is unavailable, HTTP works, and a static `AISA_API_KEY` or equivalent secret is already configured separately: read the full direct HTTP section of [Agent Quickstart fallbacks](https://aisa.one/docs/agent-quickstart-fallbacks.md) (endpoint docs, pricing, approval XML) before a paid proposal, cost approval, or paid request. Browser OAuth does not manufacture that static key. Extra models, REST, keys, or skills: [AIsa docs](https://aisa.one/docs).

docs.json

@@ -168,6 +168,7 @@
           },
           {
             "tab": "API Reference",
+            "openapi": "openapi.yaml",
             "groups": [
               {
                 "group": "Overview",
@@ -2222,6 +2223,7 @@
           },
           {
             "tab": "API 参考",
+            "openapi": "openapi.yaml",
             "groups": [
               {
                 "group": "概览",

guides/agent-discovery.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Agent Discovery – Let Autonomous Agents Find and Use AIsa"
-description: "Integrate autonomous agents with AIsa using the A2A Agent Card, MCP manifest, OpenAI plugin manifest, OpenAPI 3.1 spec, and llms.txt resources."
+description: "Find AIsa capabilities through the product Agent Card, OpenAPI spec, Docs Skill, and documentation indexes. The Docs-hosted card is not an A2A runtime."
 ---
 
 AIsa publishes several machine-readable discovery resources so that autonomous agents can find, understand, and invoke supported capabilities. This guide explains the main resources and the discovery-to-invocation flow.
@@ -11,16 +11,23 @@ AIsa exposes the following public URLs for agent and documentation discovery. Th
 
 | Endpoint | Protocol | URL | Purpose |
 | :--- | :--- | :--- | :--- |
-| **Agent Card** | Google A2A | `https://aisa.one/.well-known/agent-card.json` | High-level capabilities with metadata, tags, examples, and I/O modes |
+| **Product Agent Card** | Landing metadata | `https://aisa.one/.well-known/agent-card.json` | High-level capabilities with metadata, tags, examples, and I/O modes. Not an AIsa A2A execution runtime. |
+| **Docs Agent Card** | Mintlify auto | `https://aisa.one/docs/.well-known/agent-card.json` | Auto-derived from the published Docs Skill (`skill.md`). Same source as the canonical `aisa` Skill. Not an A2A runtime. |
 | **AI Plugin** | OpenAI Plugin (v1) | `https://aisa.one/.well-known/ai-plugin.json` | Backward compatibility with ChatGPT-era agent tooling |
 | **MCP Catalogue** | Live MCP inventory | `https://mcp.aisa.one/servers` | Entry points (root `mcp.aisa.one/mcp`, domain aliases), modules and per-server endpoints, generated by the running service |
-| **OpenAPI Spec** | OpenAPI 3.1.0 | `https://aisa.one/openapi.yaml` | Machine-readable request and response contracts |
+| **OpenAPI Spec** | OpenAPI 3.1.0 | `https://aisa.one/openapi.yaml` | Machine-readable request and response contracts. Use this when you need the API contract. |
 | **Product llms.txt** | llms.txt | `https://aisa.one/llms.txt` | Product fit, goals, interfaces, and evaluation routes |
 | **Technical llms.txt** | llms.txt | `https://aisa.one/docs/llms.txt` | Technical documentation router |
+| **API Reference** | Docs index | `https://aisa.one/docs/api-reference` | Human-readable endpoint index |
+| **Docs API catalog** | Mintlify `rel=api-catalog` | `https://aisa.one/docs/.well-known/api-catalog` | Advertised in Docs `Link` headers. **Currently 404** on `aisa.one` and `aisa.mintlify.dev`. Do not treat this URL as a working catalog. |
+
+<Warning>
+Mintlify advertises `https://aisa.one/docs/.well-known/api-catalog` on Docs responses, including 404s. That path is not a working catalog today. Use `https://aisa.one/openapi.yaml`, `https://aisa.one/docs/llms.txt`, or `https://aisa.one/docs/api-reference` instead. This page does not claim the catalog 404 is fixed.
+</Warning>
 
 ## How Agent Discovery Works
 
-The discovery flow follows three steps: **discover**, **inspect**, and **invoke**. An autonomous agent starts by fetching the agent card to learn what AIsa can do, selects the relevant skill, and then calls the corresponding API endpoint using the OpenAPI spec for request/response schemas.
+The discovery flow follows three steps: **discover**, **inspect**, and **invoke**. An autonomous agent starts by fetching a published card or Skill, selects the relevant capability, and then calls the corresponding API endpoint using the OpenAPI spec for request/response schemas. The Docs-hosted card is a Mintlify Skill projection, not an A2A transport.
 
 <Steps>
   <Step title="Discover">
@@ -34,9 +41,9 @@ The discovery flow follows three steps: **discover**, **inspect**, and **invoke*
   </Step>
 </Steps>
 
-## The A2A Agent Card
+## Agent cards
 
-The [Agent2Agent (A2A) Protocol](https://a2a-protocol.org/latest/) defines a standard format for agents to advertise capabilities and interoperate. AIsa's agent card lives at the well-known URL and describes the platform, authentication requirements, and public capability catalog.
+The product card at `https://aisa.one/.well-known/agent-card.json` is a landing metadata document. The Docs-hosted card at `https://aisa.one/docs/.well-known/agent-card.json` is generated by Mintlify from the same-source Skill published as repo-root `skill.md`. Fetch the live card instead of copying a fixed skill list. Neither URL adds an A2A execution runtime or a new well-known name.
 
 ### Fetching the Agent Card
 

scripts/sync_canonical_aisa_skill.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Export AIsa-team/agent-skills platform/aisa into the Mintlify root skill.md.
+
+Mintlify overrides the auto-generated Docs skill with a repo-root skill.md.
+The one documented transform rewrites the relative LICENSE link to the pinned
+raw GitHub URL so the license stays at the official source. Merge the Skill
+commit before this pin.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import sys
+from pathlib import Path
+
+SOURCE_SHA = "e7809490a186af77c4b96a5c1cfeea1ee39ce4f9"
+SOURCE_SKILL = "platform/aisa/SKILL.md"
+EXPORTED = "skill.md"
+EXPORTED_SHA256 = "8ccb3903800b3b97a093d36e1c90bee4d70ca705ada6d2a2dc59ef132d0b636f"
+LICENSE_RELATIVE = "MIT — see [LICENSE](LICENSE)."
+LICENSE_CANONICAL_URL = (
+    f"https://raw.githubusercontent.com/AIsa-team/agent-skills/"
+    f"{SOURCE_SHA}/platform/aisa/LICENSE"
+)
+LICENSE_ABSOLUTE = f"MIT — see [LICENSE]({LICENSE_CANONICAL_URL})."
+
+
+def export_text(skill: str) -> str:
+    if LICENSE_RELATIVE not in skill:
+        raise SystemExit(f"{SOURCE_SKILL} is missing the relative LICENSE link")
+    return skill.replace(LICENSE_RELATIVE, LICENSE_ABSOLUTE)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", type=Path, default=Path.cwd())
+    parser.add_argument("--source-dir", type=Path, help="platform/aisa directory at the pinned SHA")
+    parser.add_argument("--check", action="store_true")
+    args = parser.parse_args()
+    root = args.root.resolve()
+    source_dir = args.source_dir.resolve() if args.source_dir else None
+    exported = root / EXPORTED
+
+    if args.check:
+        errors: list[str] = []
+        if not exported.is_file():
+            errors.append(f"missing {EXPORTED}")
+        else:
+            actual = exported.read_text(encoding="utf-8")
+            digest = hashlib.sha256(actual.encode()).hexdigest()
+            if digest != EXPORTED_SHA256:
+                errors.append(f"{EXPORTED} sha256 {digest} != pinned {EXPORTED_SHA256}")
+            if LICENSE_RELATIVE in actual:
+                errors.append(f"{EXPORTED} still has a relative LICENSE link")
+            if LICENSE_CANONICAL_URL not in actual:
+                errors.append(f"{EXPORTED} is missing the pinned LICENSE URL")
+            if source_dir is not None:
+                expected = export_text((source_dir / "SKILL.md").read_text(encoding="utf-8"))
+                if actual != expected:
+                    errors.append(f"{EXPORTED} drifted from source-dir at {SOURCE_SHA}")
+        if errors:
+            print("canonical aisa skill check failed:", file=sys.stderr)
+            for error in errors:
+                print(f"- {error}", file=sys.stderr)
+            return 1
+        print(f"{EXPORTED} matches {SOURCE_SHA}")
+        return 0
+
+    if source_dir is None:
+        raise SystemExit("--source-dir is required to write the export")
+    text = export_text((source_dir / "SKILL.md").read_text(encoding="utf-8"))
+    exported.write_text(text, encoding="utf-8")
+    digest = hashlib.sha256(text.encode()).hexdigest()
+    print(f"wrote {exported.relative_to(root)} from {SOURCE_SHA} sha256={digest}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

skill.md

@@ -0,0 +1,47 @@
+---
+name: aisa
+description: "Discover and invoke published AIsa tools with the AIsa CLI (search, schema, quote, call) or unified MCP. Use when the user wants AIsa tools or sign-in, or needs current web, company, or social data AIsa tools can fetch—even if they do not name AIsa. Do not use for OpenClaw Chinese model provider setup (aisa-provider), installing other catalog skills, or work that does not need live AIsa data."
+license: MIT
+---
+
+# AIsa
+
+If you are already reading this skill, continue the current task. Do not reinstall it, reread setup docs, or relogin a working connection.
+
+If the user named another tool, or a dedicated local tool already covers the job, do not force AIsa.
+
+First-time install and connect: https://aisa.one/docs/agent-quickstart.md
+
+## Reuse
+
+Reuse a working official `aisa` skill, `@aisa-one/cli` **0.5.0 or later**, stored CLI credentials, or a unified MCP session. An explicit user transport choice or a still-authorized connection wins. Otherwise prefer the CLI on a user-local machine (PowerShell counts); prefer MCP on Grok Bot or another cloud sandbox even when a terminal exists. `AISA_API_KEY` overrides stored CLI credentials and never refreshes. If they conflict, explain the sources and leave custom setup alone. Never print credentials. Do not read or refresh token or compatibility key files. `aisa whoami` may refresh stored tokens and is not protected auth proof. Search and schema may be anonymous — they are not auth proof.
+
+## Sign-in
+
+Prove CLI auth with `aisa balance`. Before replying to a sign-in message or writing to its terminal, read `aisa login --help`. Follow it to interpret the CLI prompt and relay only the requested authorization result through the existing process. No credit → top up, not “missing key”.
+
+## Workflow
+
+`search` → `schema` when `has_full_schema` is false → `quote` → `call` inside authorized scope and spend. `quote` and `call` share the saved credentials and the same `calls` JSON shape. Take tool IDs and arguments from search/schema. Do not invent IDs or prices. Runtime help, schema, and quote are authoritative. `--input` is inline JSON:
+
+```sh
+aisa search --input '{"query":"<user goal>"}' --json
+aisa quote --input '{"calls":[{"call_id":"c1","tool":"<name from search>","arguments":{}}]}' --json
+```
+
+Quote does not execute and is not approval to execute. A missing, failed, or partial quote is not free and is not a full-batch total or cap. Estimated cost is not a cap. Setup is not paid execution permission. Reuse a still-valid explicit authorization; do not invent confirmation loops for search, schema, or install. Re-quote if tools, arguments, or scope change. Do not silently retry or expand the batch.
+
+## MCP
+
+Use native remote Streamable HTTP MCP with OAuth at `https://tools.aisa.one/mcp`. No CLI, npm, npx, or Skill installation is required; already-installed guidance may be used. The client owns browser sign-in and tokens. Do not treat domain MCP or `aisa connect`’s default web-search server as this router. Discovery or a 401 is not a protected call. If a connector cannot be added, give the user that endpoint and one next action; do not claim connected.
+
+| MCP tool | CLI command |
+| --- | --- |
+| `AISA_SEARCH_TOOL` | `aisa search` |
+| `AISA_BATCH_GET_SCHEMA` | `aisa schema` |
+| `AISA_BATCH_QUOTE` | `aisa quote` |
+| `AISA_BATCH_USE` | `aisa call` |
+
+## License
+
+MIT — see [LICENSE](https://raw.githubusercontent.com/AIsa-team/agent-skills/e7809490a186af77c4b96a5c1cfeea1ee39ce4f9/platform/aisa/LICENSE).