AIsa-team · eddiearc · Sep 9, 2026 · Sep 9, 2026 · Sep 9, 2026 · Sep 9, 2026
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -1,13 +1,11 @@
 # Release — publish to npm when a v* tag is pushed.
 #
-# The tag is the publish button. `git push origin v0.5.0` triggers this;
+# The tag is the publish button. `git push origin v0.5.1` triggers this;
 # a push to main runs CI only.
 #
-# npm Trusted Publisher must be configured for repository AIsa-team/cli and
-# workflow release.yml before a tag can publish. This workflow has not
-# recorded a successful OIDC publish. Until that setup exists, `npm publish`
-# 403s and the tag is harmless. Do not add NODE_AUTH_TOKEN or change these
-# permissions.
+# npm Trusted Publisher is configured for repository AIsa-team/cli and
+# workflow release.yml. v0.5.0 published via OIDC (GitHub Actions run
+# 34305298596). Do not add NODE_AUTH_TOKEN or change these permissions.
 #
 # The job publishes the smoke-tested tarball, not a second pack of the
 # source tree. A tag that does not match package.json is refused.

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,11 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.5.0] — Unreleased
+## [0.5.1] — 2026-09-10
 
-PR21 command-surface cleanup. Distinct from the unpublished `0.4.0` main
-baseline (registry latest remains `0.3.0`; `0.4.0` was never tagged or
-published).
+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
 
@@ -41,7 +62,7 @@ published).
 ## [0.4.0] — unpublished main baseline
 
 Unpublished `main` candidate as of 2026-09-08. Not tagged and not on npm
-(registry latest remains `0.3.0`). Kept so the Router work and the
+(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
@@ -385,7 +406,8 @@ 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.5.0...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

diff --git a/README.md b/README.md
@@ -14,8 +14,8 @@ 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
 
 # Discover published tools (Router; search/schema may be anonymous)
 aisa search "company facts" --json
@@ -25,17 +25,19 @@ aisa schema get_financial_company_facts --json
 aisa api list
 aisa api show financial
 
-# Chat with any model
-aisa chat "Explain quantum computing" --model claude-opus-4-6
-
-# Quote then execute a published Router tool (same request JSON)
+# Quote a published Router tool (does not execute)
 aisa quote --input '{"calls":[{"call_id":"c1","tool":"get_financial_company_facts","arguments":{"ticker":"AAPL"}}]}' --json
-aisa call --input '{"calls":[{"call_id":"c1","tool":"get_financial_company_facts","arguments":{"ticker":"AAPL"}}]}' --json
 ```
 
-Get your API key at
-[console.aisa.one/api-keys](https://console.aisa.one/api-keys). New accounts
-receive $5 in free credits.
+`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
@@ -102,8 +104,10 @@ 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: `AISA_API_KEY`, then `~/.aisa/key`, then legacy
-login. `aisa login` and `AISA_API_KEY` are alternatives. The default Router
+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
@@ -319,7 +323,8 @@ Settings:
   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 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`

diff --git a/docs/release.md b/docs/release.md
@@ -8,58 +8,60 @@ that commit is merged and reviewed. A push to `main` runs CI only;
 
 | Item | Value |
 | --- | --- |
-| Version | `0.5.0` (unpublished candidate; recheck registry before tagging) |
+| Version | `0.5.1` (release target) |
 | Command surface | 22 root help entries including implicit `help`; `api` is `list`/`show` only |
-| Registry latest (recheck before tagging) | `0.3.0` on `https://registry.npmjs.org` |
+| Registry latest | `0.5.0` on `https://registry.npmjs.org` (baseline at this preparation; recheck before tagging) |
 | Default Router origin | `https://tools.aisa.one` |
 | LLM / catalog host | `https://api.aisa.one` |
 | Node | `engines` `>=18`. CI on Ubuntu: 18/20 legacy compatibility, 22/24 maintained, 26 current. Publish job uses Node 24 and npm `11.6.0`. |
 
 `package.json`, `package-lock.json` (root / `packages[""]`),
 `src/constants.ts` `VERSION`, installed `aisa --version`, and
-`CHANGELOG.md` `## [0.5.0]` must agree. Confirm with
+`CHANGELOG.md` `## [0.5.1]` must agree. Confirm with
 `node scripts/package-smoke.mjs` (or `--tarball` of the candidate
 archive). The VS Code extension is not version-bumped with this CLI
 release unless its own packaging requires it.
 
 The packed archive must include `dist/index.js`, the `aisa` bin, and
-`LICENSE` (MIT, Copyright (c) 2026 AIsa Team).
+`LICENSE` (MIT, Copyright (c) 2026 AIsa Team). `eval/` stays out of the
+npm package.
 
 ## Trusted Publisher
 
-Before the first tag that should ship, configure npm Trusted Publisher
-on `https://www.npmjs.com/package/@aisa-one/cli` → Settings → Trusted
+npm Trusted Publisher is configured on
+`https://www.npmjs.com/package/@aisa-one/cli` → Settings → Trusted
 Publisher:
 
 - Repository: `AIsa-team/cli`
 - Workflow: `release.yml`
 
-Do not add a stored npm token, disable 2FA, or change GitHub
-`id-token` permissions. Until this is configured, the publish step 403s
-and the tag is harmless. Do not treat OIDC publish as already proven.
+`v0.5.0` published via OIDC (GitHub Actions run `34305298596`). Do not
+add a stored npm token, disable 2FA, or change GitHub `id-token`
+permissions. Claim a new release only after that tag's workflow and the
+official registry agree.
 
 ## Tag from reviewed main
 
 ```bash
 # Official registry only — do not use a mirror as the source of truth.
 npm view @aisa-one/cli version --registry https://registry.npmjs.org
-# expected while 0.5.0 is unpublished: 0.3.0
+# baseline at this preparation: 0.5.0 — recheck before tagging
 # 0.4.0 is the unpublished main baseline, not a registry release.
 
 git checkout main
 git pull origin main
-# Confirm this commit is the reviewed merge of the 0.5.0 candidate.
-node -p "require('./package.json').version"   # 0.5.0
-grep -E '^export const VERSION' src/constants.ts   # "0.5.0"
+# Confirm this commit is the reviewed merge of the 0.5.1 candidate.
+node -p "require('./package.json').version"   # 0.5.1
+grep -E '^export const VERSION' src/constants.ts   # "0.5.1"
 
-git tag -a v0.5.0 -m "v0.5.0"
-git push origin v0.5.0
+git tag -a v0.5.1 -m "v0.5.1"
+git push origin v0.5.1
 ```
 
 Do not tag a worktree or unmerged branch. Do not run `npm publish` on a
-laptop. Do not retag or force-push `v0.5.0`. Do not push a tag whose
-`v*` suffix differs from `package.json` `version` (the workflow refuses
-that mismatch).
+laptop. Do not retag or force-push `v0.5.0` or `v0.5.1`. Do not push a
+tag whose `v*` suffix differs from `package.json` `version` (the
+workflow refuses that mismatch).
 
 ## What the Release workflow publishes
 
@@ -76,15 +78,14 @@ again via `prepack`). It:
 Local smoke of an existing archive:
 
 ```bash
-node scripts/package-smoke.mjs --tarball /path/to/aisa-one-cli-0.5.0.tgz
+node scripts/package-smoke.mjs --tarball /path/to/aisa-one-cli-0.5.1.tgz
 ```
 
 `prepack` (`npm run build`) is what puts `dist/` into a clean `npm pack`.
 CI still runs an explicit `npm run build` before `npm test`.
 
 ## After the tag
 
-Watch the Release workflow. Success is `0.5.0` on
-`https://registry.npmjs.org/@aisa-one/cli`. A 403 means Trusted Publisher
-is still missing — configure it on npmjs.com, then decide whether to
-re-run the workflow on the same tag.
+Watch the Release workflow. Success is `0.5.1` on
+`https://registry.npmjs.org/@aisa-one/cli`. Recheck the official registry
+before assuming the tag published. Do not retag `v0.5.0`.
diff --git a/eval/agent-quickstart/README.md b/eval/agent-quickstart/README.md
@@ -0,0 +1,61 @@
+# Quickstart Skill ablation
+
+Default-off Pi ablation of **Skill context** under a fixed Quickstart guide. Four cases × `--condition skill|no-skill`. Same rubric. **Not** `eval/cli-guidance`. Do not reuse those scores. This is not causal proof of docs optimization.
+
+Install / `aisa login` / MCP are **Mock E2E**. Native npx, browser OAuth, and MCP OAuth are not claimed. Router `search`/`schema`/`quote`/`call` use the existing stub. No production AIsa credentials; no unrestricted shell.
+
+Required flags: `--docs` `--docs-sha` `--skill` `--skill-sha` `--install-meta` `--out`. Optional: `--condition skill|no-skill`, `--case ID`.
+
+`--install-meta` is `install-meta.json` from `eval/cli-guidance/run.mjs` archive/pack. Do not pass a free `--cli-bin`.
+
+Pinned: Pi **0.84.4**, `openai-codex` / `gpt-5.6-luna`, thinking `low`.
+
+See [last-run-summary.md](last-run-summary.md) for the frozen R2 inputs/results and the immutable historical R1 reference. Using different input revisions measures a new candidate.
+
+```sh
+node --test eval/agent-quickstart/grade-checks.mjs
+
+# Pack the exact CLI commit once (R1 used 19cc8bd52850c78fa57e8dc80a767f4bdfb796e1).
+node eval/cli-guidance/run.mjs --self-check --suite candidate \
+  --src /path/to/cli --expect-sha 19cc8bd52850c78fa57e8dc80a767f4bdfb796e1 \
+  --out /tmp/aisa-quickstart-pack
+
+# Use the exact source revisions listed in last-run-summary.md for R2.
+AISA_TEST_DOCS=/path/to/docs/agent-quickstart.mdx
+AISA_TEST_SKILL_REPO=/path/to/agent-skills
+AISA_TEST_OLD_SKILL=/tmp/aisa-old-SKILL.md
+AISA_TEST_LEAN_SKILL="$AISA_TEST_SKILL_REPO/search-research/aisa/SKILL.md"
+AISA_TEST_META=/tmp/aisa-quickstart-pack/install/candidate/install-meta.json
+git -C "$AISA_TEST_SKILL_REPO" show 0fcff274b6522f57b85a0eaf0c6298781c7c17c5:search-research/aisa/SKILL.md > "$AISA_TEST_OLD_SKILL"
+AISA_TEST_DOCS_SHA=$(shasum -a 256 "$AISA_TEST_DOCS" | cut -d ' ' -f1)
+AISA_TEST_OLD_SHA=$(shasum -a 256 "$AISA_TEST_OLD_SKILL" | cut -d ' ' -f1)
+AISA_TEST_LEAN_SHA=$(shasum -a 256 "$AISA_TEST_LEAN_SKILL" | cut -d ' ' -f1)
+
+node eval/agent-quickstart/run.mjs --self-check \
+  --docs "$AISA_TEST_DOCS" --docs-sha "$AISA_TEST_DOCS_SHA" \
+  --skill "$AISA_TEST_OLD_SKILL" --skill-sha "$AISA_TEST_OLD_SHA" \
+  --install-meta "$AISA_TEST_META" --out /tmp/aisa-qs-self
+```
+
+After independent clearance (12 runs = 4 cases × old Skill, lean Skill, no Skill):
+
+```sh
+AISA_EVAL_SCORE_CLEARED=1 node eval/agent-quickstart/run.mjs \
+  --docs "$AISA_TEST_DOCS" --docs-sha "$AISA_TEST_DOCS_SHA" \
+  --skill "$AISA_TEST_OLD_SKILL" --skill-sha "$AISA_TEST_OLD_SHA" \
+  --install-meta "$AISA_TEST_META" --condition skill --out /tmp/aisa-qs-old-skill
+
+AISA_EVAL_SCORE_CLEARED=1 node eval/agent-quickstart/run.mjs \
+  --docs "$AISA_TEST_DOCS" --docs-sha "$AISA_TEST_DOCS_SHA" \
+  --skill "$AISA_TEST_LEAN_SKILL" --skill-sha "$AISA_TEST_LEAN_SHA" \
+  --install-meta "$AISA_TEST_META" --condition skill --out /tmp/aisa-qs-lean-skill
+
+AISA_EVAL_SCORE_CLEARED=1 node eval/agent-quickstart/run.mjs \
+  --docs "$AISA_TEST_DOCS" --docs-sha "$AISA_TEST_DOCS_SHA" \
+  --skill "$AISA_TEST_LEAN_SKILL" --skill-sha "$AISA_TEST_LEAN_SHA" \
+  --install-meta "$AISA_TEST_META" --condition no-skill --out /tmp/aisa-qs-no-skill
+```
+
+`--case ID` limits to one of `cold-start-authorized`, `reuse-authorized`, `no-terminal-oauth-pending`, `no-spend-hard-cap`.
+
+`AISA_EVAL_SCORE_CLEARED=1` is a local review guard, not user authentication. Wrong/unresolved provider or model exits 2; any failed task or safety check exits 1.