fix: polish Altimate connect dialog — default URL, rename labels, fix placeholder (#724)

* fix: polish Altimate connect dialog — default URL, rename labels, fix placeholder

- parseAltimateKey now accepts `instance-name::api-key` (URL defaults to
  https://api.myaltimate.com); `api-url::instance-name::api-key` still
  works for custom/self-hosted instances.
- Provider display name: "Altimate" → "Altimate AI".
- Default model display name: "Altimate AI" → "Altimate LLM Gateway".
- TUI input placeholder for altimate-backend changed from "API key" to
  "instance-name::api-key" so it matches the expected format.
- Dialog copy, example, and validation error message updated to reflect
  the new default-URL form with custom-URL fallback.
- Docs (docs/docs/getting-started.md) and tests updated accordingly.

Internal IDs (`altimate-backend`, `altimate-default`) are intentionally
left unchanged to preserve auth-store / config compatibility.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor: parseAltimateKey uses part-count, not URL sniffing

Drop the `://` heuristic for detecting whether the user supplied an
API URL. Rule is now purely positional:

- split("::").length == 2 → URL omitted → default to
  https://api.myaltimate.com
- length >= 3 → first segment IS the URL; validated as http(s)://

This matches the mental model "if split on :: gives 2, no URL".
It also means a 2-part API key cannot contain `::`; that's an
acceptable trade-off because Altimate keys don't use `::`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor: rename model ID altimate-default → altimate-llm-gateway

The display name is already "Altimate LLM Gateway" — the ID should
match instead of staying as the opaque "altimate-default".

Touched:
- packages/opencode/src/provider/provider.ts (model registration +
  default-selection + log message)
- packages/opencode/src/acp/agent.ts (default-selection)
- packages/opencode/test/provider/provider.test.ts (assertions)
- packages/opencode/test/skill/release-v0.5.20-adversarial.test.ts
  (parseModel test fixture)
- docs/docs/configure/providers.md (tip text)

Provider ID `altimate-backend` intentionally left alone — that one is
an auth-storage / credential-file boundary and renaming it has a much
larger blast radius. CHANGELOG.md left alone — historical record.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: say 'select Altimate AI' to match renamed provider display

Addresses review feedback from Copilot and cubic-dev-ai: the
getting-started guide instructed users to select **Altimate** in the
/connect TUI, but the provider display name is now **Altimate AI**.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: add JSDoc to parseAltimateKey describing the two accepted formats

Addresses Coderabbit pre-merge docstring-coverage check by documenting
the 2-part (default URL) vs 3+ part (custom URL) behavior of
parseAltimateKey.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: revert model ID rename (backward-compat) + resolve review comments

Addresses two review findings:

1. cubic P1 — renaming the internal model ID from `altimate-default` to
   `altimate-llm-gateway` broke backward compatibility. Opencode
   persists selected model IDs to `model.json` (favorites, recents,
   variants) and users can pin `model: altimate-backend/altimate-default`
   in their opencode.json. After the rename those references would
   silently go stale. Keep the ID as `altimate-default`; the polish the
   user actually wanted was the display name, which stays as
   "Altimate LLM Gateway". Added a comment explaining why the ID is
   preserved. Rephrased the auto-selection tip in
   `docs/docs/configure/providers.md` to refer to the display name
   rather than the internal ID.

2. Coderabbit — the custom-URL example in `docs/docs/getting-started.md`
   used `api-url::instance-name::api-key` which is ambiguous; the parser
   requires `http(s)://`. Replaced with a concrete
   `https://api.example.com::...` example and added a sentence stating
   the scheme is required.

Also reverted provider.ts, acp/agent.ts, provider.test.ts, and
release-v0.5.20-adversarial.test.ts to use the original `altimate-default`
ID.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: suryaiyer95

docs/docs/configure/providers.md

@@ -39,7 +39,7 @@ Managed LLM access with dynamic routing across Sonnet 4.6, Opus 4.6, GPT-5.4, GP
 For pricing, security, and data handling details, see the [Altimate LLM Gateway guide](https://datamates-docs.myaltimate.com/user-guide/components/llm-gateway/).
 
 !!! tip "Automatic model selection"
-    When Altimate credentials are configured and no model is explicitly chosen, `altimate-backend/altimate-default` is selected automatically. You can override this by setting `model` in your config or by restricting the `provider` section to specific providers only.
+    When Altimate credentials are configured and no model is explicitly chosen, the Altimate LLM Gateway is selected automatically. You can override this by setting `model` in your config or by restricting the `provider` section to specific providers only.
 
 ## Anthropic
 

docs/docs/getting-started.md

@@ -83,18 +83,25 @@ For all warehouse types (Snowflake, BigQuery, Databricks, PostgreSQL, Redshift,
 
 ### Connecting to Altimate
 
-If you have an Altimate platform account, run `/connect` in the TUI, select **Altimate**, and enter your credentials in this format:
+If you have an Altimate platform account, run `/connect` in the TUI, select **Altimate AI**, and enter your credentials in this format:
 
 ```text
-instance-url::instance-name::api-key
+instance-name::api-key
 ```
 
-For example: `https://api.getaltimate.com::acme::your-api-key`
+For example: `acme::your-api-key` — this uses the default API URL `https://api.myaltimate.com`.
 
-- **Instance URL** — `https://api.myaltimate.com` or `https://api.getaltimate.com` depending on your dashboard domain
 - **Instance Name** — the subdomain from your Altimate dashboard URL (e.g. `acme` from `https://acme.app.myaltimate.com`)
 - **API Key** — go to **Settings > API Keys** in your Altimate dashboard and click **Copy**
 
+If your instance uses a different API URL (e.g. a self-hosted or `getaltimate.com` deployment), prepend the full URL — it must include the `http://` or `https://` scheme, hostname-only values will fail validation:
+
+```text
+https://api.example.com::instance-name::api-key
+```
+
+For example: `https://api.getaltimate.com::acme::your-api-key`
+
 Credentials are validated against the Altimate API before being saved. If you prefer to configure credentials directly (e.g. for CI or environment variable substitution), you can also create `~/.altimate/altimate.json` manually — if that file exists it takes priority over the TUI-entered credentials.
 
 **`altimate.json` schema:**

packages/opencode/src/altimate/api/client.ts

@@ -4,6 +4,9 @@ import { Global } from "../../global"
 import { Filesystem } from "../../util/filesystem"
 
 const DEFAULT_MCP_URL = "https://mcpserver.getaltimate.com/sse"
+// altimate_change start — default Altimate API URL when user omits it from the TUI credential entry
+const DEFAULT_ALTIMATE_URL = "https://api.myaltimate.com"
+// altimate_change end
 
 const AltimateCredentials = z.object({
   altimateUrl: z.string(),
@@ -81,18 +84,40 @@ export namespace AltimateApi {
     }
   }
 
+  /**
+   * Parse a user-entered Altimate credential string into its component fields.
+   *
+   * Accepts two `::`-delimited forms:
+   *   - 2 parts: `instance-name::api-key` — URL defaults to {@link DEFAULT_ALTIMATE_URL}.
+   *   - 3+ parts: `api-url::instance-name::api-key` — first segment is the API base URL
+   *     and must be http(s)://. Extra `::` segments are joined back into the API key.
+   *
+   * Returns `null` if the input is malformed (fewer than 2 parts, empty fields,
+   * or a non-http(s) URL in the 3-part form).
+   */
   export function parseAltimateKey(value: string): {
     altimateUrl: string
     altimateInstanceName: string
     altimateApiKey: string
   } | null {
     const parts = value.trim().split("::")
-    if (parts.length < 3) return null
-    const url = parts[0].trim()
-    const instance = parts[1].trim()
-    const key = parts.slice(2).join("::").trim()
+    // altimate_change start — 2 parts means no URL was given (use default); 3+ parts means URL was given
+    if (parts.length < 2) return null
+    let url: string
+    let instance: string
+    let key: string
+    if (parts.length === 2) {
+      url = DEFAULT_ALTIMATE_URL
+      instance = parts[0].trim()
+      key = parts[1].trim()
+    } else {
+      url = parts[0].trim()
+      instance = parts[1].trim()
+      key = parts.slice(2).join("::").trim()
+    }
     if (!url || !instance || !key) return null
     if (!url.startsWith("http://") && !url.startsWith("https://")) return null
+    // altimate_change end
     return { altimateUrl: url, altimateInstanceName: instance, altimateApiKey: key }
   }
 

packages/opencode/src/cli/cmd/tui/component/dialog-provider.tsx

@@ -217,10 +217,14 @@ function ApiMethod(props: ApiMethodProps) {
   const [validationError, setValidationError] = createSignal<string | null>(null)
   // altimate_change end
 
+  // altimate_change start — altimate-backend placeholder matches the credential format
+  const placeholder = props.providerID === "altimate-backend" ? "instance-name::api-key" : "API key"
+  // altimate_change end
+
   return (
     <DialogPrompt
       title={props.title}
-      placeholder="API key"
+      placeholder={placeholder}
       description={
         {
           opencode: (
@@ -252,10 +256,13 @@ function ApiMethod(props: ApiMethodProps) {
                 Enter your Altimate credentials in this format:
               </text>
               <text fg={theme.text}>
-                instance-url::instance-name::api-key
+                instance-name::api-key
+              </text>
+              <text fg={theme.textMuted}>
+                e.g. mycompany::abc123 (uses https://api.myaltimate.com)
               </text>
               <text fg={theme.textMuted}>
-                e.g. https://api.getaltimate.com::mycompany::abc123
+                For a custom API URL, use: api-url::instance-name::api-key
               </text>
               <Show when={validationError()}>
                 <text fg={theme.error}>{validationError()!}</text>
@@ -271,7 +278,7 @@ function ApiMethod(props: ApiMethodProps) {
         if (props.providerID === "altimate-backend") {
           const parsed = AltimateApi.parseAltimateKey(value)
           if (!parsed) {
-            setValidationError("Invalid format — use: instance-url::instance-name::api-key")
+            setValidationError("Invalid format — use: instance-name::api-key (or api-url::instance-name::api-key for a custom URL)")
             return
           }
           const validation = await AltimateApi.validateCredentials(parsed)

packages/opencode/src/provider/provider.ts

@@ -1115,10 +1115,14 @@ export namespace Provider {
     // altimate_change start — register altimate-backend as an OpenAI-compatible provider
     if (!database["altimate-backend"]) {
       const backendModels: Record<string, Model> = {
+        // ID "altimate-default" is kept for backward compatibility — existing
+        // users have it persisted in their model.json favorites/recents and in
+        // opencode.json `model:` entries. Display name ("Altimate LLM Gateway")
+        // is what the TUI actually shows, so branding stays correct.
         "altimate-default": {
           id: ModelID.make("altimate-default"),
           providerID: ProviderID.make("altimate-backend"),
-          name: "Altimate AI",
+          name: "Altimate LLM Gateway",
           family: "openai",
           api: { id: "altimate-default", url: "", npm: "@ai-sdk/openai-compatible" },
           status: "active",
@@ -1141,7 +1145,7 @@ export namespace Provider {
       }
       database["altimate-backend"] = {
         id: ProviderID.make("altimate-backend"),
-        name: "Altimate",
+        name: "Altimate AI",
         source: "custom",
         env: [],
         options: {},

packages/opencode/test/altimate/datamate.test.ts

@@ -270,10 +270,41 @@ describe("parseAltimateKey", () => {
     expect(r?.altimateApiKey).toBe("key::extra")
   })
 
-  test("returns null for too few parts", () => {
-    expect(AltimateApi.parseAltimateKey("https://api.getaltimate.com::mycompany")).toBeNull()
+  test("returns null for a single part (no separator)", () => {
+    expect(AltimateApi.parseAltimateKey("justonevalue")).toBeNull()
   })
 
+  // altimate_change start — default URL for 2-part input
+  test("parses 2-part input with default URL (https://api.myaltimate.com)", () => {
+    const r = AltimateApi.parseAltimateKey("mycompany::abc123")
+    expect(r).toEqual({
+      altimateUrl: "https://api.myaltimate.com",
+      altimateInstanceName: "mycompany",
+      altimateApiKey: "abc123",
+    })
+  })
+
+  test("trims whitespace for 2-part input", () => {
+    const r = AltimateApi.parseAltimateKey("  mycompany :: abc123  ")
+    expect(r?.altimateUrl).toBe("https://api.myaltimate.com")
+    expect(r?.altimateInstanceName).toBe("mycompany")
+    expect(r?.altimateApiKey).toBe("abc123")
+  })
+
+  test("returns null for empty instance name in 2-part input", () => {
+    expect(AltimateApi.parseAltimateKey("::abc123")).toBeNull()
+  })
+
+  test("returns null for empty api key in 2-part input", () => {
+    expect(AltimateApi.parseAltimateKey("mycompany::")).toBeNull()
+  })
+
+  test("3+ parts always treat first segment as URL — non-http rejected", () => {
+    // `mycompany::key::extra` → 3 parts → url=mycompany (fails http(s) check)
+    expect(AltimateApi.parseAltimateKey("mycompany::key::extra")).toBeNull()
+  })
+  // altimate_change end
+
   test("returns null for empty url", () => {
     expect(AltimateApi.parseAltimateKey("::mycompany::key")).toBeNull()
   })