@synqa/cli 1.1.0 → 1.2.0

package/README.md

@@ -12,7 +12,7 @@ Blink 5.5, Sonata 6.0 and Aeon 6.5.
 - [Slash commands](#slash-commands)
 - [Welcome panel and turn footer](#welcome-panel-and-turn-footer)
 - [Diff preview](#diff-preview)
-- [Status bar](#status-bar)
+- [Status line](#status-line)
 - [AGENTS.md and /init](#agentsmd-and-init)
 - [Undo](#undo)
 - [Settings and environment](#settings-and-environment)
@@ -22,7 +22,7 @@ Blink 5.5, Sonata 6.0 and Aeon 6.5.
 
 ## Install
 
-Needs Node.js 22.18 or newer (or 23.6 or newer) and npm. There are no other dependencies. **Not published to npm yet:** `npx` and the installer work only after the first release.
+Needs Node.js 22.18 or newer (or 23.6 or newer) and npm. There are no other dependencies.
 
 Try it without installing:
 
@@ -59,72 +59,146 @@ From a checkout of this repo (for development): `npm link ./cli`.
 2. Paste your `synqa_live_...` key (typing is hidden). It is checked against the Synqa API and
    saved to `~/.config/synqa/config.json` (file mode 0600).
 
-Or skip login and set `SYNQA_API_KEY` in your shell. The variable wins over the saved key.
+Or set `SYNQA_API_KEY` in your shell. A key saved by `synqa login` or `/login` wins over the variable,
+so you never need to unset it; pass `--env-key` to make the variable win for one run.
+
+Starting `synqa` in a terminal with no valid Synqa key shows the welcome screen and asks for the key
+first (typing shows `••••`, the key is checked at `https://api.synqa.ca/v1/account`). Chat and every
+other provider stay locked until you are signed in to Synqa Cloud.
+
+## Providers
+
+After you sign in, `/provider` (or `/login`) opens an arrow-key menu: Synqa Cloud (primary),
+OpenCode Go, OpenCode Zen, OpenRouter (bring your own `sk-or-...` key) and a custom
+OpenAI-compatible endpoint. Keys for the others are typed masked, checked with `GET /v1/models` and
+saved in the same private config file (mode 0600 on macOS and Linux; Windows ignores the mode). The
+active provider and model show in the header and the footer. `/logout` offers to leave the secondary
+provider or to log out fully, which clears the Synqa key (and `SYNQA_API_KEY` in this process) and
+returns to the sign-in prompt. Use `OPENCODE_API_KEY` or the router's key variable as a fallback when
+nothing is saved.
+
+## Keys and modes
+
+- `/` opens the command list under the prompt: Up/Down move, Tab fills, Enter runs, Esc closes.
+- `/model`, `/effort`, `/provider`, `/login`, `/logout` and `/hooks` with no argument open an inline
+  Up/Down list (Enter selects, Esc cancels).
+- Shift+Tab cycles the permission mode: `ask before edits`, `auto-accept edits` (file edits in the
+  workspace apply without a question, like `--yes`; shell commands still ask) and `plan only` (no
+  file is written and no command is run). The mode shows in the footer.
+
+## Hooks
+
+`.synqa/hooks.json` in a project and `hooks.json` in the user config folder can run shell commands at
+`SessionStart`, `PreToolUse`, `PostToolUse` and `Stop`:
+
+```json
+{ "hooks": { "PreToolUse": [ { "matcher": "write_file|edit_file", "command": "python check.py" } ] } }
+```
+
+The hook gets the event as JSON on stdin. A `PreToolUse` hook blocks the tool by exiting with code 2
+or printing `{"decision":"block","reason":"..."}`; other output is ignored. A command that starts
+with `python` runs with `python3` (or `py` on Windows) when `python` is not on PATH. Project hooks
+are repository content, so they start off: `/hooks` lists them and switches them on or off.
+
+### Hooks security
+
+- Project hooks start disabled. An approval is tied to the project path and the exact entry
+  (command, matcher and timeout): a different folder or any edit to the entry needs a new approval.
+- The hook payload includes the tool input and result (up to 4000 characters each), so a hook sees
+  file contents and command output.
+- Never point a hook at a file the agent can write: the agent could rewrite the script that runs next.
+- In plan only mode the `PostToolUse` and `Stop` hooks do not run.
+
+## Updates
+
+On start `synqa` asks the npm registry once, with a 1.5 second limit and no error message, whether a
+newer `@synqa/cli` exists, and shows a quiet hint in the footer. `/update` runs
+`npm install -g @synqa/cli@latest`. Set `SYNQA_NO_UPDATE_CHECK=1` to skip the check.
 
 ## Use
 
 - `synqa` : interactive session in the current folder.
 - `synqa "fix the failing test"` : one task, then exit.
-- `synqa --yes "..."` : run unattended. **`--yes` runs shell commands without asking, so use it only in repositories you trust**
+- `synqa --yes "..."` : approve ordinary file writes and edits inside the folder without asking. **Shell commands always ask, even with `--yes`** (any file the agent reads could carry an injected command), and `--yes` is not allowed in your home folder
   (text in a README or a web page can steer the model). Some things still ask, and are denied when nobody can answer:
   writes that can run code later (git hooks and other `.git` files, `package.json`, Makefiles, `.envrc`, `.vscode`
   settings, CI workflows, shell startup files, dotfiles, executables), writes to secrets files, every write and
   shell command while an `AGENTS.md` is loaded, and shell commands that name a secrets file or a glob that could.
   Diffs are still shown.
 - `synqa --model sonata` : start on another tier (`blink`, `sonata`, `aeon`).
-- `synqa --effort low` : start with a reasoning effort (`default`, `low`, `medium`).
+- `synqa --effort low` : start with a reasoning effort (`default`, `low`, `medium`, `high`).
 
 ## Slash commands
 
 | Command | What it does |
 |---|---|
-| `/model blink\|sonata\|aeon` | Switch tier. With no argument it shows the current one. |
-| `/effort default\|low\|medium` | Set the reasoning effort. `default` sends no effort setting. |
+| `/model blink\|sonata\|aeon` | Choose the model. With no argument an arrow-key list opens: Blink 5.5, Sonata 6.0, Aeon 6.5 on Synqa Cloud, the provider's own model list otherwise. |
+| `/effort default\|low\|medium\|high` | Set the reasoning effort (arrow-key list with no argument). `default` sends no effort setting. |
+| `/provider`, `/login` | Pick Synqa Cloud, OpenCode Go, OpenCode Zen, OpenRouter or a custom endpoint. |
+| `/logout` | Leave the secondary provider, or log out fully and lock the session. |
+| `/hooks` | List hooks and switch them on or off. |
+| `/update` | Install the latest `@synqa/cli`. |
 | `/status` | Tier, routing, session tokens, context use of the last request, and your live credit and weekly pool balance. |
 | `/init` | Scan the project and write a starter `AGENTS.md`. |
 | `/compact` | Ask the model to summarize the conversation and continue from the summary, to save context. |
 | `/undo` | Revert the last file the agent wrote. Run it again to go further back. |
 | `/clear` | Start a fresh conversation (reloads `AGENTS.md`). |
-| `/help` | List the commands. |
+| `/help` | List the commands, grouped, with the keys of the command menu. |
 | `/exit` | Leave (also `/quit`, or Ctrl-D). |
 
 `/status` reads your balance from the Synqa account service with your key. If the service does not
 answer, it says so and shows everything else; your balance is always on the
 [dashboard](https://synqa.ca/client-dashboard).
 
-## Welcome panel and turn footer
+## Start screen, prompt and turn footer
 
-In an interactive terminal the session opens with a welcome panel: the CLI version, the tier id and
-name, the workspace folder (your home folder shown as `~`), whether `AGENTS.md` project notes were
-loaded, and your credit and weekly pool balance from the Synqa account service. The balance lookup
-waits at most 2 seconds; if it fails the panel says `balance unavailable`, and `balance not available yet`
-when the service does not offer it to API keys yet. Your key is never shown.
+In an interactive terminal the session opens with the Synqa wordmark (on a window of 60 columns or
+more; a one-line bold `Synqa.` below that), then dim lines with the CLI version, tier and effort, and
+the workspace folder (your home folder shown as `~`), then short `⎿` notes: whether `AGENTS.md`
+project notes were loaded, and your credit and weekly pool balance from the Synqa account service.
+The balance lookup waits at most 2 seconds; if it fails the note says `balance unavailable`, and
+`balance not available yet` when the service does not offer it to API keys yet. Your key is never shown.
 
 ```
-╭─ Synqa. CLI v1.1.0 ───────────────────────────────────────────╮
-│ ╭────╮  Tier       synqa-sonata-6.0 (Sonata 6.0)              │
-│ │ S. │  Workspace  ~/proj                                     │
-│ ╰────╯  Notes      AGENTS.md loaded (1,234 chars)             │
-│         Balance    $9.98 credit · weekly pool $4.00 of $10.00 │
-╰───────────────────────────────────────────────────────────────╯
+  ▄▀▀▀
+   ▀▀▄ █  █ █▀▀▄ ▄▀▀█ ▄▀▀█
+  ▄▄▄▀ ▀▄▄█ █  █ ▀▄▄█ ▀▄▄█ ▄
+       ▄▄▄▀         █
+
+  v1.2.0 · Blink 5.5 · default effort
+  ~/synqa-test
+  ⎿ no AGENTS.md yet: /init writes one
+  ⎿ $9.98 credit · weekly pool $4.00 of $10.00
+───────────────────────────────────────────────────────────────────────────────
+❯ Try "explain this project", or type / for commands
+───────────────────────────────────────────────────────────────────────────────
+Blink 5.5 · synqa-test · 0 tokens                                  $9.98 credit
+/ commands · ↑↓ history · tab complete · ctrl+c quit
 ```
 
-On a terminal that is not UTF-8 (or `TERM=dumb`, or a very old Windows console) the panel is plain ASCII:
-
-```
-[S.] Synqa. CLI v1.1.0
-  Tier       synqa-sonata-6.0 (Sonata 6.0)
-  Workspace  ~/proj
-  Notes      AGENTS.md loaded (1,234 chars)
-  Balance    $9.98 credit | weekly pool $4.00 of $10.00
-```
-
-Colours: terracotta for the period, spinner, `❯` prompt and monogram; warm bone for the name and the
-tier; warm stone for borders, labels and the footer; sage for the balance and added diff lines
-(removed lines stay red). 24-bit colour is used when `COLORTERM` is `truecolor` or `24bit`, otherwise
-the nearest of the 256 terminal colours. Stone is a mid grey: row labels are bold to stay readable,
-but on a light terminal background borders and the footer are faint.
-
+The letters are drawn in your terminal's own text colour, so they read as ink on a light theme and
+light on a dark one; the full stop is terracotta. The input sits between two thin rules, with a dim
+hint while it is empty. Under it the status line shows only what is known (see below) and a line of
+key hints.
+
+Type `/` and a menu of commands opens under the input, filtered as you type, with a short
+description of each. Up and Down move the highlight, Tab or Enter completes it (Enter runs a command
+that takes no argument), Esc closes the menu. An unknown command gets a one-line hint with the
+nearest name. The menu is drawn with Node's own readline key events, no extra package.
+
+On a terminal that is not UTF-8 (or `TERM=dumb`, or a very old Windows console) everything is plain
+ASCII and there is no menu or frame: the status is printed above a plain `>` prompt.
+
+Colours: terracotta for the full stop, spinner, `❯` prompt, tier name and the selected menu row;
+the terminal's own text colour (bold) for names, or warm bone when the terminal reports a dark
+background (`COLORFGBG`); warm stone for rules and labels; sage for the balance and added diff lines
+(removed lines stay red). 24-bit colour is used only where it is known to work: `COLORTERM` is
+`truecolor` or `24bit`, or `TERM_PROGRAM` is iTerm2, WezTerm, VS Code, Ghostty and similar. macOS
+Terminal.app (`TERM_PROGRAM=Apple_Terminal`) and unknown terminals get the 256 standard colours, with
+terracotta mapped to colour 166 so it stays burnt orange; Terminal.app gets them even when a
+`COLORTERM` was copied into the shell profile, because it misdraws 24-bit escapes. Every line is
+measured by its visible width (colour codes not counted, wide characters counted as two) and kept
+one column short of the window, so nothing wraps.
 
 While the agent waits for the first token a spinner with the elapsed seconds is shown (`⠋ waiting 1.2s`)
 and is erased when output starts. Each tool call is drawn as a card: a header with the tool and its
@@ -143,10 +217,10 @@ file or command, the diff preview for edits inside it, and a one line result.
 After every turn a dim footer line stays in the scrollback: time to first token, output speed,
 routing (`local` or `hybrid`) and your credit left (only when the balance is known).
 
-The panel, spinner, cards and footer degrade on their own: with `NO_COLOR` they have no colour; when
+The start screen, spinner, cards and footer degrade on their own: with `NO_COLOR` they have no colour; when
 output is not a terminal (a pipe, a file, a one-shot task) there is no spinner, no cursor control and
 the old plain output; when the terminal is not UTF-8, is `TERM=dumb`, or is the old Windows console
-(Windows Terminal is fine), the panel, cards and spinner use plain ASCII (`[S.]`, `+-`, `| / - \`). Long paths are cut with an
+(Windows Terminal is fine), the start screen, cards and spinner use plain ASCII (`+-`, `| / - \`). Long paths are cut with an
 ellipsis to fit narrow windows. Text from the model or from tools never reaches the terminal as
 control sequences.
 
@@ -161,24 +235,26 @@ shell startup files, other dotfiles): those are always shown in full.
 Colour is off when output is not a terminal or when `NO_COLOR` is set; the diff is then plain `+`/`-`
 text. Control characters in file content are shown as `\x1b`-style escapes, never sent to your terminal.
 
-## Status bar
+## Status line
 
-In an interactive terminal the last row of the screen stays pinned and shows:
+In an interactive terminal the line under the input shows only values that are known:
 
 ```
-Blink 5.5 | local | TTFT 0.42s | 87.3 tok/s | 1,234 tokens
+Blink 5.5 · low effort · synqa-test · ctx 10% · hybrid · 1,234 tokens          $9.98 credit
 ```
 
-- Tier display name (`Blink 5.5`, `Sonata 6.0` or `Aeon 6.5`), plus `effort low` or `effort medium` when set.
+- Tier display name (`Blink 5.5`, `Sonata 6.0` or `Aeon 6.5`), plus `low effort` or `medium effort` when set.
+- The workspace folder name.
+- `ctx`: how much of the context window the last request used (after the first request).
 - Routing: `local` or `hybrid`, read from the `x-synqa-routing` response header of the last request
-  (`fallback` for a fallback route, `?` if the server did not say).
-- TTFT: seconds from sending the request to the first token. tok/s: output tokens per second of
-  generation over the last turn. A dash means the number was not reported.
+  (`fallback` for a fallback route); left out when the server did not say.
 - Session tokens: input plus output so far.
+- On the right, your credit when the balance is known.
 
-On a narrow terminal the least important parts drop off first. When the output is not a terminal
-(a pipe, a file, a very small window, `TERM=dumb`) there is no pinned bar: the same line is printed
-above each prompt, and after a one-shot task.
+On a narrow terminal the least important parts drop off first. Time to first token and output speed
+are in the footer after each turn. When the output is not a terminal (a pipe, a file, `TERM=dumb`)
+a plain line (`Blink 5.5 | local | TTFT 0.42s | 87.3 tok/s | 1,234 tokens`, unknown parts left out)
+is printed above each prompt, and after a one-shot task.
 
 ## AGENTS.md and /init
 
@@ -203,7 +279,7 @@ it. Use git for that.
 
 | Name | Meaning |
 |---|---|
-| `SYNQA_API_KEY` | Your key; wins over the saved one. Never passed to commands the agent runs. |
+| `SYNQA_API_KEY` | Your key. A key saved by `synqa login` or `/login` wins over it unless you pass `--env-key`. Never passed to commands the agent runs. |
 | `NO_COLOR` | Any non-empty value turns colour off. |
 | `~/.config/synqa/config.json` | Saved key and default tier (mode 0600). |
 
@@ -211,7 +287,7 @@ it. Use git for that.
 
 - File tools only touch files inside the folder you started in (`..`, absolute paths and symlinks
   out of it are refused).
-- Writes, edits and shell commands ask `y/N` first, also in one-shot mode, unless `--yes`. Without a
+- Writes and edits ask `y/N` first, also in one-shot mode, unless `--yes`; shell commands always ask. Every question shows the whole diff (only the display after a `--yes` approval is cut). Commands run without credential-looking environment variables (tokens, secrets, keys and passwords by name, `AWS_*` except region and profile, git askpass helpers, connection strings with a password in them, the API key, and `SSH_AUTH_SOCK`: run `git push` over SSH in your own terminal). `grep` stops a pattern that runs longer than 10 seconds. Without a
   terminal the answer is no.
 - Shell commands are not confined to the folder: read each one before you answer.
 - Writes to `.git/hooks`, `package.json`, shell startup files and other dotfiles carry a warning, because
@@ -220,21 +296,33 @@ it. Use git for that.
   delimited block as conventions only, you are told when it is loaded, and while it is loaded shell
   commands always ask first, even with `--yes`.
 - Files that hold secrets (`.env` and `.env.*` except examples, `.envrc`, `*.pem`, `*.key`, `*.tfvars`, `id_*`
-  private keys, `keys.json`, `credentials.json`, `secrets.*`, `.ssh/`, `.aws/`, `.gnupg/`, `.kube/config`,
-  `.docker/config.json`, `.netrc`, `.npmrc`, `.pypirc`, `.git-credentials`, `.dev.vars`, this CLI's own config)
-  are opened (read or edit) only after you say yes, never with `--yes`, and are skipped by `grep` and `glob`.
+  private keys, `keys.json`, `credentials.json`, `secrets.*`, `.ssh/`, `.aws/`, `.gnupg/`, `.kube/`,
+  `.docker/config.json`, `.netrc`, `.npmrc`, `.pypirc`, `.git-credentials`, `.dev.vars`, `.config/gh`,
+  `.config/gcloud`, `.azure/`, `.password-store/`, macOS keychains (`Library/Keychains`, `*.keychain-db`),
+  browser profiles (Chrome, Chromium, Brave, Edge, Arc, Firefox, Safari, cookies and saved logins), this
+  CLI's own config) are never read, written or edited by the agent, with or without `--yes`, and are
+  skipped by `grep` and `glob`. A shell command that names one always asks first, even with `--yes`.
   Names match without regard to case or full-width letters, as on a case-insensitive Mac.
-- The CLI refuses to start in your home folder or the filesystem root (it could reach your keys and
-  settings there). Pass `--allow-home` only if you mean it.
+- The CLI starts in any folder, your home folder included, like other coding CLIs. Inside your home
+  folder everything under a dot entry at its top (`~/.zsh_history`, `~/.config/...`, `~/.cargo/...`,
+  any tool's settings) and everything under `~/Library` is protected as a rule, whether or not it is
+  named above; your projects' own dot files (`~/proj/.github`) are not affected. `--yes` is refused
+  in the home folder itself. Writes to launchd agents, autostart entries, systemd units, fish and
+  other shell startup files and `~/.local/bin` always ask. Only the filesystem root (`/`) is refused
+  as a start folder. `--allow-home` is still accepted and does nothing.
 - Your key is never printed, never put on a command line, and removed from the environment of every
   command the agent runs.
 
 ## Troubleshooting
 
 - `No API key`: run `synqa login` or set `SYNQA_API_KEY`.
-- `the key was rejected`: the key was revoked or mistyped; make a new one on the dashboard.
+- `Your API key was rejected`: run `synqa login` again, or check on the dashboard that the key is
+  active. A key saved with `/login` is used before `SYNQA_API_KEY`; `/logout` then `Full logout` clears
+  both in the running session.
+- `synqa login` checks the key against the same key check the chat uses, and refuses a key with no
+  chat access.
 - `request timed out`: a request is cut off after 10 minutes.
-- Status bar garbled after resizing: it repaints on resize.
+- Stray characters or a broken layout in Terminal.app: update to 1.1.1, which uses 256 colours there.
 - No colour: check `NO_COLOR` and that stdout is a terminal.
 
 ## Develop

package/dist/agent.js

@@ -13,7 +13,7 @@ export const MAX_NOTES_CHARS = 8000;
 // from a third party (a cloned repo), so it goes in a delimited block as data: conventions only,
 // never an instruction source. fenceText removes invisible characters and neutralizes every "<", so
 // nothing inside can open or close the block.
-export function systemPrompt(tier      , cwd        , notes         )         {
+export function systemPrompt(tier      , cwd        , notes         , external = false)         {
   const body = fenceText(notes ?? "", MAX_NOTES_CHARS);
   const extra = body
     ? [
@@ -26,8 +26,10 @@ export function systemPrompt(tier      , cwd        , notes         )         {
     ]
     : [];
   return [
-    `You are Synqa-${tier.display}, a terminal coding agent made by Synqa.`,
-    "If asked what model you are or who created you, say you are Synqa and name your tier; say nothing else about what runs inside.",
+    external
+      ? "You are the Synqa terminal coding agent, running on a model provider the user chose. If asked who created this tool, say Synqa."
+      : `You are Synqa-${tier.display}, a terminal coding agent made by Synqa.`,
+    ...(external ? [] : ["If asked what model you are or who created you, say you are Synqa and name your tier; say nothing else about what runs inside."]),
     `Working directory: ${cwd}. File tools cannot leave it.`,
     "Use the tools to read, search and change files and to run commands. Make small, correct changes and say briefly what you did.",
     ...extra,
@@ -52,6 +54,15 @@ export function systemPrompt(tier      , cwd        , notes         )         {
                       
                      
                      
+                                                                              
+                                                                                         
+                    
+  
+
+// PreToolUse and PostToolUse hooks. pre returns a reason to block the tool, or undefined to run it.
+                         
+                                                                   
+                                                                      
   
 
                          
@@ -78,7 +89,8 @@ export async function runAgent(o            )                     {
     o.events.onRequest?.();
     const r = await chat({
       apiKey: o.apiKey,
-      model: o.tier.id,
+      model: o.modelId ?? o.tier.id,
+      baseUrl: o.baseUrl,
       messages: o.history,
       tools: TOOL_DEFS,
       fetchFn: o.fetchFn,
@@ -109,7 +121,9 @@ export async function runAgent(o            )                     {
       o.events.onTool(c.name, c.arguments);
       let result        ;
       try {
-        result = await runTool(o.ctx, c.name, parseToolArguments(c.arguments));
+        const blocked = await o.hooks?.pre(c.name, c.arguments);
+        result = blocked !== undefined ? `blocked by a hook: ${blocked}` : await runTool(o.ctx, c.name, parseToolArguments(c.arguments));
+        if (blocked === undefined) await o.hooks?.post(c.name, c.arguments, result);
       } catch (err) {
         result = `error: ${err instanceof Error ? err.message : String(err)}`;
       }

package/dist/api.js

@@ -1,4 +1,5 @@
-import { API_BASE } from "./config.js";
+import { API_BASE, DASHBOARD_URL } from "./config.js";
+import { sanitize } from "./sanitize.js";
 import { REQUEST_TIMEOUT_MS, MAX_OUTPUT_TOKENS, usageFrom } from "./tiers.js";
                                         
 
@@ -90,9 +91,48 @@ export class ApiError extends Error {
   }
 }
 
+export const KEY_REJECTED = `Your API key was rejected. Run \`synqa login\` again, or check the key is active in your Synqa dashboard (${DASHBOARD_URL}).`;
+
+// The gateway's short reason ({"detail": "..."}), already white-labelled by the server; sanitized
+// and cut here because it is network text.
+async function detailOf(res          )                  {
+  try {
+    const text = (await res.text()).slice(0, 4000);
+    const v = JSON.parse(text)                                                       ;
+    const d = typeof v.detail === "string" ? v.detail : typeof v.error?.message === "string" ? v.error.message : "";
+    return sanitize(d).replace(/\s+/g, " ").trim().slice(0, 200);
+  } catch {
+    return "";
+  }
+}
+
+// A plain sentence for a failed request, by status. Never the raw body.
+export function friendlyStatus(status        , detail = "")         {
+  const why = detail ? ` (${detail})` : "";
+  if (status === 401) return KEY_REJECTED;
+  if (status === 402) return `Your Synqa balance is used up or your plan is not active${why}. Top up in your Synqa dashboard (${DASHBOARD_URL}).`;
+  if (status === 403) return `This key is not allowed to do that${why}. Check the key's access in your Synqa dashboard (${DASHBOARD_URL}).`;
+  if (status === 404) return "The Synqa service did not recognise this request (404). Update the CLI: npm i -g @synqa/cli";
+  if (status === 413) return `The conversation is too large to send${why}. Run /compact or /clear and try again.`;
+  if (status === 429) return `Rate limit reached${why}. Wait a moment and try again.`;
+  if (status === 503) return `Synqa is busy or paused right now${why}. Try again in a minute.`;
+  if (status >= 500) return `The Synqa service had a problem (status ${status}). Try again in a minute.`;
+  return `The request failed with status ${status}${why}.`;
+}
+
+// Login check: GET /v1/models goes through the same key check as chat (the gateway's caller_key),
+// and the list is empty for a key without the chat capability, so an empty list is refused too.
 export async function checkKey(apiKey        , fetchFn            = fetch)                {
   const res = await fetchFn(`${API_BASE}/models`, { headers: { authorization: `Bearer ${apiKey}` } });
-  if (!res.ok) throw new ApiError(res.status, res.status === 401 || res.status === 403 ? "the key was rejected" : `unexpected status ${res.status}`);
+  if (!res.ok) throw new ApiError(res.status, res.status === 401 ? "the key was rejected" : friendlyStatus(res.status, await detailOf(res)));
+  let ids            = [];
+  try {
+    const body = (await res.json())                      ;
+    ids = Array.isArray(body.data) ? body.data : [];
+  } catch {
+    throw new ApiError(res.status, "the service answer was not understood");
+  }
+  if (ids.length === 0) throw new ApiError(403, "this key has no chat access; check it in your Synqa dashboard");
 }
 
                            
@@ -101,6 +141,7 @@ export async function checkKey(apiKey        , fetchFn            = fetch)
                       
                    
                       
+                                                                            
                                
                      
                                                                     
@@ -114,7 +155,7 @@ export async function chat(o             )                      {
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), o.timeoutMs ?? REQUEST_TIMEOUT_MS);
   try {
-    const res = await fetchFn(`${API_BASE}/chat/completions`, {
+    const res = await fetchFn(`${(o.baseUrl ?? API_BASE).replace(/\/+$/, "")}/chat/completions`, {
       method: "POST",
       headers: { authorization: `Bearer ${o.apiKey}`, "content-type": "application/json" },
       body: JSON.stringify({
@@ -128,7 +169,8 @@ export async function chat(o             )                      {
       }),
       signal: ac.signal,
     });
-    if (!res.ok || !res.body) throw new ApiError(res.status, `request failed with status ${res.status}`);
+    if (!res.ok) throw new ApiError(res.status, friendlyStatus(res.status, res.status === 401 ? "" : await detailOf(res)));
+    if (!res.body) throw new ApiError(res.status, "the service sent an empty answer");
     const acc = new StreamAccumulator();
     let firstAt                    ;
     for await (const ev of sseEvents(res.body                                        )) {