@jiayunxie/aerial 0.1.5 → 0.1.7

package/README.md

@@ -3,278 +3,122 @@
 [![CI](https://github.com/Xiejiayun/aerial/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Xiejiayun/aerial/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@jiayunxie/aerial.svg)](https://www.npmjs.com/package/@jiayunxie/aerial)
 
-Aerial is a lightweight local-only proxy that lets one user connect their own GitHub Copilot subscription to local coding CLIs.
+Aerial lets Codex CLI and Claude Code use your own GitHub Copilot subscription through a local proxy on your machine.
 
-The MVP runs on `127.0.0.1:18181`, requires a local Aerial API key for model routes, stores credentials on the user's machine, and avoids public deployment, account sharing, quota bypass, dashboards, analytics, and image APIs.
+It runs locally on `127.0.0.1:18181`. Your GitHub token and Aerial key stay on your machine. It is built for personal local use, not for public hosting or account sharing.
 
-## MVP Support
-
-Implemented routes:
-
-- `GET /health` without auth
-- `GET /v1/models` for model discovery, with an `aerial` support annotation per model
-- `POST /v1/responses` for Codex CLI
-- `POST /v1/messages` for Claude Code's Anthropic gateway path
-- `POST /v1/messages/count_tokens` with a local estimate
-- `POST /v1/chat/completions` as a simple passthrough fallback
-
-Implemented CLI commands:
-
-```bash
-aerial login
-aerial key generate
-aerial key print
-aerial start
-aerial setup codex [--model <responses-model-id>]
-aerial setup claude [--model <messages-model-id>]
-aerial setup status
-aerial setup restore <codex|claude|all> --latest
-aerial service install
-aerial service start
-aerial service status
-aerial service stop
-aerial service restart
-aerial service uninstall
-aerial disable
-aerial doctor
-aerial probe
-```
-
-Rollback safety net, log file rotation, and bundled service management (macOS launchd + Windows Task Scheduler) are part of this release. Gemini CLI support, Linux service management, dashboards, and analytics are intentionally out of this MVP. For Codex, local clients keep using HTTP POST /v1/responses. Aerial can optionally use Copilot's upstream `ws:/responses` transport for streaming Responses and translate events back to SSE — this transport is opt-in (`AERIAL_RESPONSES_WEBSOCKET=on`) and HTTP is the default.
+## Install
 
-## Requirements
+Requirements:
 
 - Node.js 22+
 - A GitHub account with an active Copilot subscription
-- Codex CLI and/or Claude Code installed locally
-
-## Install
+- Codex CLI and/or Claude Code installed
 
 ```bash
 npm install -g @jiayunxie/aerial
 ```
 
-After install, the CLI is available as `aerial`.
-
-### Nightly builds (advanced, unstable)
-
-Nightly pre-releases are published by the same `release.yml` workflow as stable releases, dispatched with `mode=nightly` (and, once scheduled publishing is enabled, by a daily cron on the same workflow). They are routed through a single workflow because npm only allows one trusted publisher per package. The default install command above is unaffected — nightlies are gated behind the `@nightly` dist-tag and will never be served as `latest`. To opt in:
-
-```bash
-npm install -g @jiayunxie/aerial@nightly
-```
-
-Nightly versions look like `0.1.1-nightly.YYYYMMDD.<sha7>`. They reflect the current `main` and may break; report regressions with `aerial --version` so the exact build can be reproduced. Switch back to stable any time with `npm install -g @jiayunxie/aerial`.
-
-### From source (local development)
+## Quick Start
 
-For working directly on the Aerial codebase:
+1. Sign in to GitHub:
 
 ```bash
-git clone https://github.com/Xiejiayun/aerial.git
-cd aerial
-npm install -g .
-```
-
-Run without global install:
-
-```bash
-node src/cli.js --help
+aerial login
 ```
 
-## First Run
-
-Configure the local client you use. These commands also create Aerial's local API key and wire it into the selected client:
+2. Configure the client you use:
 
 ```bash
+# Codex CLI
 aerial setup codex
-# optional, if you use Claude Code too:
+
+# Claude Code
 aerial setup claude
 ```
 
-If Codex or Claude Code was already open, restart it after setup so it rereads the updated client config.
-
-Log in to GitHub with device flow:
-
-```bash
-aerial login
-```
+During setup, Aerial reads your Copilot model list, shows the models that work for that client, and asks which one to write into the client config. Codex uses models with the `responses` route. Claude Code uses models with the `messages` route.
 
-Install and start the background service:
+3. Start Aerial in the background:
 
 ```bash
 aerial service install
 ```
 
-Check health:
+4. Check everything from one place:
 
 ```bash
-curl http://127.0.0.1:18181/health
+aerial status
 ```
 
-## Codex CLI Setup
+If Aerial prints a hint, follow it before expecting the background service to work after reboot.
 
-Aerial configures Codex through the Responses wire API provider path:
+Restart Codex CLI or Claude Code if either one was already open while you ran setup.
 
-```bash
-aerial setup codex
-```
+## What Setup Changes
 
-This updates `~/.codex/config.toml` and creates a timestamped backup first. If you only want to inspect the exact change, set `HOME`/`USERPROFILE` to a temporary directory before running setup. The inserted provider uses:
+`aerial setup codex` updates `~/.codex/config.toml`.
 
-```toml
-[model_providers.aerial]
-base_url = "http://127.0.0.1:18181/v1"
-wire_api = "responses"
+- It points Codex at `http://127.0.0.1:18181/v1`.
+- It uses Codex's command-backed auth helper so Codex can read the local Aerial key automatically.
+- It creates a timestamped backup before writing.
 
-[model_providers.aerial.auth]
-command = "<node>"
-args = ["<aerial-cli.js>", "key", "print"]
-timeout_ms = 5000
-refresh_interval_ms = 0
-```
+`aerial setup claude` updates `~/.claude/settings.json`.
+
+- It points Claude Code at `http://127.0.0.1:18181`.
+- It configures an API key helper so Claude Code can read the local Aerial key automatically.
+- It creates a timestamped backup before writing.
 
-Aerial creates and stores the local key automatically. Codex reads it through the configured helper command, so users do not need to run `aerial key generate`, copy a key, or export `AERIAL_API_KEY`.
+You normally do not need to create, copy, or export an API key yourself.
 
-## Claude Code Setup
+## Choosing A Model
 
-Aerial configures Claude Code through its Anthropic-compatible gateway settings:
+The easiest path is to let setup show the compatible models:
 
 ```bash
+aerial setup codex
 aerial setup claude
 ```
 
-This updates `~/.claude/settings.json` and creates a timestamped backup first. If you only want to inspect the exact change, set `HOME`/`USERPROFILE` to a temporary directory before running setup. It sets:
-
-```json
-{
-  "model": "<available-copilot-model-id>",
-  "apiKeyHelper": "aerial key print",
-  "env": {
-    "ANTHROPIC_BASE_URL": "http://127.0.0.1:18181",
-    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
-  }
-}
-```
-
-The `model` field is written when you pass `--model` or set Aerial's `defaultModel`; otherwise Aerial leaves any existing Claude Code model choice alone while still switching the gateway to the local Aerial endpoint.
-
-If you need explicit models, pass `--model <responses-model-id>` to `aerial setup codex` and `--model <messages-model-id>` to `aerial setup claude`. Aerial intentionally does not provide `aerial setup all` as a setup shortcut because Codex and Claude Code may need different model IDs.
-
-`aerial key print` prints the locally stored Aerial API key for Claude Code's helper flow. Users normally do not need to call it directly.
-
-When switching from another Anthropic-compatible gateway, setup removes stale `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`, and `ANTHROPIC_DEFAULT_*_MODEL` entries from Claude Code's managed `env` block so `apiKeyHelper` and the Aerial gateway are the active route.
-
-## Diagnostics
+To pin a model without the prompt:
 
 ```bash
-aerial doctor
-aerial probe
+aerial setup codex --model <responses-model-id>
+aerial setup claude --model <messages-model-id>
 ```
 
-The doctor checks config, local API key presence, GitHub login state, Node version, and local bind address.
-
-## Security Boundary
-
-Aerial is for personal local use only.
-
-- It binds to `127.0.0.1` by default.
-- Model routes require `Authorization: Bearer <AERIAL_API_KEY>` or `x-api-key: <AERIAL_API_KEY>`.
-- GitHub tokens are stored under the user config directory with private file permissions where supported.
-- Aerial does not log raw GitHub tokens, Copilot JWTs, API keys, or request bodies by default.
-- Do not expose this service publicly or use it for account sharing.
-
-## Current Limitations
-
-- Copilot inference routes are an observed compatibility target, not a public stable GitHub REST API.
-- `/v1/messages/count_tokens` is a local estimate, not upstream tokenization.
-- Bundled service management is implemented for macOS (launchd) and Windows (Task Scheduler). On Linux, run `aerial start` directly or wrap it in your own init system.
-- For explicit model overrides, query `/v1/models`, choose a `responses` model for Codex and a `messages` model for Claude Code, then rerun the client-specific setup command with `--model`.
-- Chat Completions requests normalize `max_tokens` to `max_completion_tokens` for newer OpenAI models that reject the older field.
-- Prompt caching is upstream-managed: Aerial does not store prompt bodies locally, and it preserves or injects cache protocol fields before forwarding.
-
-
-
-## Capability Probe
-
-Use `aerial probe` to inspect the live Copilot model matrix through the same local credentials Aerial uses for proxying:
+To inspect the full model matrix:
 
 ```bash
 aerial probe
 ```
 
-This prints model IDs, Aerial routes, and unsupported notes such as `embeddings_not_implemented` or `no_supported_endpoint_advertised`. Models with upstream `ws:/responses` support are shown with the `responses_websocket` route.
-
-Run low-cost live route checks when you want to verify end-to-end behavior:
+## Daily Commands
 
 ```bash
-aerial probe --live
-# machine-readable output
-aerial probe --live --json
+aerial status           # setup, login, service, and health summary
+aerial service install  # install and start the background service
+aerial doctor           # local diagnostics
+aerial disable          # restore client configs and uninstall the service
 ```
 
-`--live` sends one small request through the first available `responses`, `messages`, and `chat` model. It does not test every model by default, which keeps the command lightweight.
-## Prompt Cache
-
-Aerial uses the upstream Copilot/OpenAI/Anthropic cache protocols instead of keeping a local prompt-content cache. That keeps the MVP lightweight and avoids storing prompts on disk.
-
-Supported behavior:
-
-- Responses and Chat Completions preserve `prompt_cache_retention` and `prompt_cache_key` when the client sends them.
-- Responses and Chat Completions automatically add `prompt_cache_retention: "in_memory"` and a stable hashed `prompt_cache_key` when the client omits them.
-- Anthropic Messages preserves client `cache_control` blocks. When none are present and caching is enabled, Aerial automatically adds `cache_control: { "type": "ephemeral" }` to stable `system` content, or to the final tool definition when there is no system content.
-- Usage fields from upstream are returned unchanged, including `cached_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`, and Copilot `cache_read` / `cache_write` token details when present.
-- Aerial logs cache metadata to stderr as `cache_request` and `cache_observe` events. These logs do not include prompt text or request bodies.
-
-OpenAI's prompt caching documentation says cache hits require an exact prompt prefix match and are only possible once the prompt is at least 1024 tokens. Confirm cache behavior from returned usage fields such as `usage.prompt_tokens_details.cached_tokens` or `usage.input_tokens_details.cached_tokens`; for shorter prompts this value is expected to be zero.
-
-Aerial enables ephemeral prompt caching by default for OpenAI-style routes and Anthropic Messages. Override it only when needed:
+`aerial start` is for foreground debugging in the current terminal. Most users should use `aerial service install`.
 
-```bash
-aerial config set promptCacheRetention in_memory
-# or
-aerial config set promptCacheRetention 24h
-# disable automatic cache hints
-aerial config set promptCacheRetention off
-aerial config set promptCacheKey off
-# pin all requests to an explicit cache partition
-aerial config set promptCacheKey my-project
-```
-
-You can also set it per process:
-
-```bash
-export AERIAL_PROMPT_CACHE_RETENTION=in_memory
-export AERIAL_PROMPT_CACHE_KEY=my-project
-```
-
-Per-request fields win over the configured default. Use `24h` only with models whose upstream route accepts extended retention; Anthropic Messages still uses Anthropic-style `cache_control: { "type": "ephemeral" }`. Set `promptCacheKey` to `auto` to use Aerial's hashed stable key, `off` to omit it, or a string to force a specific cache partition.
-## Model Support
-
-`GET /v1/models` returns Copilot's raw model metadata and adds an Aerial-specific field:
-
-```json
-{
-  "id": "gpt-5.4-mini",
-  "supported_endpoints": ["/responses", "ws:/responses"],
-  "aerial": {
-    "supported": true,
-    "routes": ["responses", "responses_websocket"],
-    "notes": []
-  }
-}
-```
+Advanced service lifecycle commands are documented in `docs/usage.md`.
 
-Route meanings:
+## Troubleshooting
 
-- `responses`: usable by Codex through HTTP `POST /v1/responses`.
-- `responses_websocket`: Aerial can use Copilot's upstream `ws:/responses` transport for streaming `/v1/responses` requests when `AERIAL_RESPONSES_WEBSOCKET=on` is set, then return SSE to the local client. When the opt-in is off (default), Aerial always uses HTTP upstream Responses even if a model advertises `ws:/responses`.
-- `messages`: usable by Claude Code through `POST /v1/messages`.
-- `chat`: usable by generic OpenAI Chat clients through `POST /v1/chat/completions`.
+- `Missing GitHub token`: run `aerial login`.
+- `Invalid or missing Aerial API key`: rerun `aerial setup codex` or `aerial setup claude`, then restart the client.
+- No models listed during setup: run `aerial login` first, then retry setup.
+- Port conflict on `18181`: run `aerial status` to see whether another process is using the port.
+- Need to undo setup: run `aerial disable`, or restore one client with `aerial setup restore <codex|claude> --latest`.
 
-Local clients should not open WebSocket connections to Aerial directly. Direct WebSocket upgrades still return `501 Not Implemented`; use HTTP `POST /v1/responses` and let Aerial choose the upstream transport. HTTP upstream Responses is the default; set `AERIAL_RESPONSES_WEBSOCKET=on` to opt into Copilot's upstream WebSocket transport for streaming Responses calls (still experimental, only effective for streaming requests on models that advertise `ws:/responses`).
+## Notes
 
-Known unsupported notes:
+- macOS background service support uses a user LaunchAgent.
+- Windows background service support uses a user Task Scheduler task.
+- Linux service management is not built in yet; run `aerial start` or use your own init system.
+- Copilot inference routes are an observed compatibility target and may change upstream.
 
-- `embeddings_not_implemented`: Aerial does not expose `/v1/embeddings` yet.
-- `no_supported_endpoint_advertised`: the model did not declare a route Aerial can safely select.
+More details: `docs/usage.md`.

package/docs/usage.md

@@ -23,12 +23,13 @@ node src/cli.js --help
 ## 2. Configure Local Clients
 
 ```bash
+aerial login
 aerial setup codex
 # optional, if you use Claude Code too:
 aerial setup claude
 ```
 
-Aerial creates a local API key, stores it privately, and configures the selected clients to use it. There is intentionally no `aerial setup all` setup shortcut: Codex and Claude Code can need different model IDs, so setup stays client-specific. If Codex or Claude Code was already open, restart it after setup so it rereads the updated client config.
+Aerial creates a local API key, stores it privately, asks you to choose from compatible Copilot models, and configures the selected clients to use it. Run `aerial login` before setup so model discovery can read your Copilot model list. There is intentionally no `aerial setup all` setup shortcut: Codex and Claude Code can need different model IDs, so setup stays client-specific. If Codex or Claude Code was already open, restart it after setup so it rereads the updated client config.
 
 ## 3. Login To GitHub
 
@@ -52,7 +53,7 @@ Default URL: `http://127.0.0.1:18181`. `aerial service install` is the daily-use
 aerial setup codex
 ```
 
-The setup command backs up and merges `~/.codex/config.toml`, then configures Codex to fetch the local Aerial key through a command-backed provider auth helper:
+The setup command backs up and merges `~/.codex/config.toml`, asks you to choose a model whose Aerial routes include `responses`, then configures Codex to fetch the local Aerial key through a command-backed provider auth helper:
 
 ```toml
 [model_providers.aerial]
@@ -70,7 +71,7 @@ The local key is generated and stored by Aerial automatically. Users do not need
 
 For a dry inspection without touching your real config, set `HOME`/`USERPROFILE` to a temporary directory before running this command.
 
-If you need to pin a model, first run `aerial probe` or call `/v1/models`, choose a model whose Aerial routes include `responses`, then run `aerial setup codex --model <responses-model-id>`.
+To skip the prompt, pass `--model <responses-model-id>`.
 
 ## 6. Configure Claude Code
 
@@ -78,21 +79,50 @@ If you need to pin a model, first run `aerial probe` or call `/v1/models`, choos
 aerial setup claude
 ```
 
-The setup command backs up and merges `~/.claude/settings.json`, using `apiKeyHelper = "aerial key print"` and `ANTHROPIC_BASE_URL=http://127.0.0.1:18181`. When you pass `--model` or set Aerial's `defaultModel`, it also writes Claude Code's default `model` to that Aerial-routed model.
+The setup command backs up and merges `~/.claude/settings.json`, asks you to choose a model whose Aerial routes include `messages`, then writes an absolute `apiKeyHelper` command and `ANTHROPIC_BASE_URL=http://127.0.0.1:18181`. The helper lets Claude Code read the local Aerial key automatically without relying on a shell `AERIAL_API_KEY` export or a refreshed `PATH`.
 
 If Claude Code was previously pointed at another Anthropic-compatible gateway, setup removes stale `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`, and `ANTHROPIC_DEFAULT_*_MODEL` entries from the managed `env` block.
 
 For a dry inspection without touching your real config, set `HOME`/`USERPROFILE` to a temporary directory before running this command.
 
-If you need to pin a model, first run `aerial probe` or call `/v1/models`, choose a model whose Aerial routes include `messages`, then run `aerial setup claude --model <messages-model-id>`.
+To skip the prompt, pass `--model <messages-model-id>`.
 
 ## 7. Verify
 
 ```bash
+aerial status
 aerial doctor
 aerial probe
 ```
 
+`aerial status` is the top-level daily check. It combines setup state, local auth files, service state, and health into one short report. Use `--json` for a machine-readable `aerial.status.v1` document.
+
+`aerial status --json` top-level fields: `schema`, `ok`, `setup`, `service`, `nextSteps`, `hints`. `nextSteps` lists actions you must take to reach `ok: true` (login / setup / service install / recover local key). `hints` lists non-blocking advisories that you should still pay attention to, such as `AERIAL_GITHUB_TOKEN` being set for the current shell only (the background service may not see it after reboot). Example:
+
+```json
+{
+  "schema": "aerial.status.v1",
+  "ok": false,
+  "nextSteps": ["run: aerial setup codex or aerial setup claude"],
+  "hints": ["AERIAL_GITHUB_TOKEN is set for this process only; run aerial login without that env var to persist a service-readable login."],
+  "setup": { "...": "aerial.setup-status.v1 fields here" },
+  "service": { "...": "aerial.service-status.v1 fields here" }
+}
+```
+
+### Local HTTP endpoints
+
+| Request | Local Aerial API key | Behavior |
+| --- | --- | --- |
+| `GET /` | not required | 200 + friendly status JSON pointing at `/health` and `aerial status`; no secrets in body |
+| `GET /health` | not required | 200 + minimal `{ ok, service, host, port }` |
+| `GET /v1/models` (with GitHub login) | not required | 200 + Copilot model list with Aerial route annotations |
+| `GET /v1/models` (no GitHub login) | not required | 401 + `error.aerial.status = "login_required"` |
+| `GET /v1/models` (GitHub login rejected by Copilot) | not required | 401/403 + `error.aerial.status = "upstream_auth_failed"` and `upstream_status` |
+| `POST /v1/responses`, `/v1/messages`, `/v1/messages/count_tokens`, `/v1/chat/completions` | required | 401 if key missing/invalid; otherwise proxied to Copilot |
+
+None of these endpoints emit `WWW-Authenticate` or open CORS (`Access-Control-Allow-Origin: *`). The `login_required` and `upstream_auth_failed` JSON shapes never include tokens, keys, or filesystem paths.
+
 Each model returned by `/v1/models` includes an `aerial` field that tells you whether the MVP can route it:
 
 ```json
@@ -131,7 +161,7 @@ aerial disable
   "config": { "host": "127.0.0.1", "port": 18181 },
   "auth": {
     "api_key":      { "file": "/Users/you/Library/Application Support/aerial/api_key", "exists": true },
-    "github_token": { "file": "/Users/you/Library/Application Support/aerial/github_token", "exists": false }
+    "github_token": { "file": "/Users/you/Library/Application Support/aerial/github_token", "exists": true, "source": "file" }
   },
   "clients": {
     "codex": {
@@ -139,7 +169,7 @@ aerial disable
       "state": "aerial",
       "file": "/Users/you/.codex/config.toml",
       "backups": ["/Users/you/.codex/config.toml.aerial-backup-2026-05-20T10-00-00-000Z"],
-      "model": "gpt-4.1",
+      "model": "gpt-5.5",
       "baseUrl": "http://127.0.0.1:18181/v1"
     },
     "claude": {
@@ -154,7 +184,9 @@ aerial disable
 }
 ```
 
-Stability rules for `aerial.setup-status.v1`: new fields may be added at any level in future Aerial releases — consumers must ignore unknown keys. Existing fields will not be removed or repurposed without bumping the `schema` value. Field types remain constant within a schema version.
+`auth.github_token.source` is one of `"missing"`, `"file"`, or `"env"`. `exists` is derived: `source !== "missing"` ("the current process can read a GitHub token"). `source = "env"` means the token came from `AERIAL_GITHUB_TOKEN`, which the background service generally cannot see — run `aerial login` without that env var to persist a service-readable login. To detect a persisted file login specifically, read `source === "file"`.
+
+Stability rules for `aerial.setup-status.v1`: new fields may be added at any level in future Aerial releases — consumers must ignore unknown keys. Existing fields will not be removed or repurposed without bumping the `schema` value. Field types remain constant within a schema version. Note: in 0.1.6, `auth.github_token.exists` reflects "process-readable" (file or env), not strictly "token file present". Downstream consumers that need the old file-only semantics should read `auth.github_token.source === "file"`.
 
 `aerial setup restore <codex|claude|all> --latest` restores the most recent `*.aerial-backup-<ISO>` snapshot for the named client. Before overwriting, it takes a `*.aerial-pre-restore-<ISO>` snapshot of the current file so the restore itself is reversible. With `all`, both clients are restored best-effort and the command exits non-zero if any individual restore failed. If there is no backup to restore, the command prints a note and exits 0.
 
@@ -191,7 +223,7 @@ Wrapper env values are baked in at install time. If you set `AERIAL_LOG_MAX_BYTE
 
 `aerial service start` enforces a similar shape: it refuses with `reason=not_installed` and exit 1 if the unit/task does not exist; it refuses with `reason=port_conflict` and exit 1 if a non-Aerial process owns the port; it refuses with `reason=foreground_running` and exit 1 if Aerial is already running in the foreground (not via the service manager); it returns idempotent success with `note=already running (service-managed)` if the service is already up; otherwise it starts the service. `aerial service stop` is idempotent (exit 0 + `note` when nothing is installed or nothing is running). `aerial service uninstall` is idempotent on the "no service installed" branch, but does NOT swallow real teardown failures: on macOS, if the service is loaded and `launchctl bootout` returns non-zero, the plist and wrapper are preserved and the command exits 1 with `reason=bootout_failed`; on Windows, if `schtasks /Delete` returns non-zero, the wrapper is preserved and the command exits 1 with `reason=delete_failed`. In both cases the message includes a retry pointer. `aerial service restart` blocks the start step when the stop step fails: if `stop` returns `ok=false`, the response includes `reason=stop_failed` and `start` is not attempted. `aerial disable` follows the same contract: it restores client configs first, then calls `serviceUninstall`. Only an `unsupported platform` exception is treated as a silent skip (Linux); any supported-platform uninstall failure (`ok=false` or non-`unsupported-platform` throw) propagates as exit 1 with a retry pointer at `aerial service uninstall`.
 
-If GitHub login is not yet configured, install and start still succeed (when reachable) and emit a structured warning pointing at `aerial login`; proxy requests return 503 until you log in. After rotating the local API key or moving the config directory, restart the service with `aerial service restart` so the new credentials are picked up.
+If GitHub login is not yet configured, install and start still succeed (when reachable) and emit a structured warning pointing at `aerial login`; inference proxy requests return 503 until you log in, while `GET /v1/models` returns 401 with `error.aerial.status = "login_required"`. After rotating the local API key or moving the config directory, restart the service with `aerial service restart` so the new credentials are picked up.
 
 `aerial service status` reports a single aggregated view:
 
@@ -321,7 +353,7 @@ Best practice: put stable system/project/tool context first, put changing user i
 
 - `503 Missing GitHub token`: run `aerial login`.
 - `401 Invalid or missing Aerial API key`: run `aerial setup codex` or `aerial setup claude` for the client you use, then restart the client terminal or VS Code.
-- Claude Code cannot read key: ensure `aerial` is on `PATH`; it uses `aerial key print` as its helper.
+- Claude Code cannot read key: rerun `aerial setup claude` so the settings file gets a fresh absolute API-key helper command.
 - Upstream compatibility error: run `aerial doctor`, then retry with a model returned by `/v1/models`.
 - `Unsupported parameter: max_tokens`: Aerial normalizes Chat Completions `max_tokens` into `max_completion_tokens` before forwarding to newer OpenAI models.
 - Cache hit stays zero: ensure the stable prefix is long enough, unchanged, and placed before variable content. For Responses/Chat, try a stable `prompt_cache_key`; for Messages, keep stable content in `system` or put manual `cache_control` on the stable content block.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiayunxie/aerial",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Local-only GitHub Copilot proxy for Codex CLI and Claude Code.",
   "type": "module",
   "private": false,

package/src/app-status.js

@@ -0,0 +1,23 @@
+export function computeAppStatus(setup, service) {
+  const githubTokenPresent = setup.auth.github_token.source !== "missing";
+  const apiKeyPresent = setup.auth.api_key.exists;
+  const hasAerialClient = setup.clients.codex.state === "aerial" || setup.clients.claude.state === "aerial";
+  const serviceHealthy = service.supported !== false && service.health?.aerial === true;
+  const ok = apiKeyPresent && githubTokenPresent && hasAerialClient && serviceHealthy;
+  const nextSteps = [];
+  const hints = [];
+  if (!githubTokenPresent) nextSteps.push("run: aerial login");
+  if (!hasAerialClient) nextSteps.push("run: aerial setup codex or aerial setup claude");
+  if (hasAerialClient && !apiKeyPresent) nextSteps.push("run: aerial setup codex or aerial setup claude to recreate the local Aerial key");
+  if (service.supported !== false && !service.service?.loaded) {
+    if (serviceHealthy) {
+      hints.push("Aerial is running in the foreground but no background service is installed; run `aerial service install` so it starts on reboot.");
+    } else {
+      nextSteps.push("run: aerial service install");
+    }
+  }
+  if (setup.auth.github_token.source === "env") {
+    hints.push("AERIAL_GITHUB_TOKEN is set for this process only; run aerial login without that env var to persist a service-readable login.");
+  }
+  return { schema: "aerial.status.v1", ok, setup, service, nextSteps, hints };
+}

package/src/auth.js

@@ -48,9 +48,20 @@ export async function pollDeviceFlow(deviceCode, intervalSeconds) {
 }
 
 export function readGitHubToken() {
-  if (process.env.AERIAL_GITHUB_TOKEN) return process.env.AERIAL_GITHUB_TOKEN;
+  const envToken = process.env.AERIAL_GITHUB_TOKEN?.trim();
+  if (envToken) return envToken;
   if (!fs.existsSync(githubTokenPath())) return undefined;
-  return fs.readFileSync(githubTokenPath(), "utf8").trim();
+  const fileToken = fs.readFileSync(githubTokenPath(), "utf8").trim();
+  return fileToken || undefined;
+}
+
+export function gitHubTokenSource() {
+  if (process.env.AERIAL_GITHUB_TOKEN?.trim()) return "env";
+  if (fs.existsSync(githubTokenPath())) {
+    const fileToken = fs.readFileSync(githubTokenPath(), "utf8").trim();
+    if (fileToken) return "file";
+  }
+  return "missing";
 }
 
 function jwtExpirySeconds(token) {
@@ -71,7 +82,11 @@ export async function exchangeCopilotToken(githubToken = readGitHubToken()) {
       "user-agent": "Aerial/0.1"
     }
   });
-  if (!response.ok) throw new Error(`Copilot token exchange failed: ${response.status} ${await response.text()}`);
+  if (!response.ok) {
+    const err = new Error(`Copilot token exchange failed: ${response.status} ${await response.text()}`);
+    err.aerialUpstreamStatus = response.status;
+    throw err;
+  }
   const payload = await response.json();
   const token = payload.token;
   if (!token) throw new Error("Copilot token exchange response did not include token");
@@ -90,3 +105,8 @@ export async function getCopilotToken({ force = false } = {}) {
   }
   return refreshPromise;
 }
+
+export function _resetCopilotTokenCacheForTests() {
+  cachedCopilotToken = undefined;
+  refreshPromise = undefined;
+}