docs: add OpenCode guide, split Goose out, fix LibreChat accuracy

cloud/guides/integrations/cline-roo-kilo.mdx

@@ -168,4 +168,5 @@ Sources checked on 2026-06-23: Cline OpenAI Compatible provider docs, Roo Code O
 - [Available Models](/cloud/models)
 - [Continue](/cloud/guides/integrations/continue)
 - [Aider and Zed](/cloud/guides/integrations/aider-zed)
-- [OpenCode and Goose](/cloud/guides/opencode-goose)
+- [OpenCode](/cloud/guides/integrations/opencode)
+- [Goose](/cloud/guides/opencode-goose)

cloud/guides/integrations/index.mdx

@@ -21,11 +21,12 @@ Use the OpenAI client guide when you are configuring code directly. Use the inte
 
 ### Coding agents and IDEs
 
+- [OpenCode](/cloud/guides/integrations/opencode)
 - [Cursor](/cloud/guides/integrations/cursor)
 - [Continue](/cloud/guides/integrations/continue)
 - [Cline, Roo Code, and Kilo Code](/cloud/guides/integrations/cline-roo-kilo)
 - [Aider and Zed](/cloud/guides/integrations/aider-zed)
-- [OpenCode and Goose](/cloud/guides/opencode-goose)
+- [Goose](/cloud/guides/opencode-goose)
 
 ### Self-hosted and team apps
 

cloud/guides/integrations/librechat.mdx

@@ -29,17 +29,21 @@ Do not append `/chat/completions` to `baseURL`. LibreChat appends the chat-compl
 Use the NEAR AI Cloud gateway model ID:
 
 ```text
-z-ai/glm-5.2
+z-ai/glm-5.3-flash
 ```
 
 Check [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery) before adding newer model IDs.
 
+<Note>
+Retired NEAR AI model IDs are kept as aliases onto their successor, so an older ID such as `z-ai/glm-5.2` still resolves today. Prefer the canonical ID from `/v1/models`; an alias can be repointed without notice.
+</Note>
+
 ## Configure
 
 Create or edit `librechat.yaml` in the LibreChat project root:
 
 ```yaml librechat.yaml
-version: 1.3.13
+version: 1.3.16
 cache: true
 
 endpoints:
@@ -49,13 +53,24 @@ endpoints:
       baseURL: 'https://cloud-api.near.ai/v1'
       models:
         default:
-          - 'z-ai/glm-5.2'
+          - 'z-ai/glm-5.3-flash'
       titleConvo: true
-      titleModel: 'z-ai/glm-5.2'
+      titleModel: 'z-ai/glm-5.3-flash'
       modelDisplayLabel: 'NEAR AI Cloud'
+      customParams:
+        reasoningFormat: reasoning_object
+        reasoningKey: reasoning_content
 ```
 
-The custom endpoint name `nearai` is intentionally not a built-in LibreChat endpoint name. Do not add a `provider` field for NEAR AI Cloud; LibreChat uses the OpenAI-compatible custom endpoint path when that field is omitted.
+The custom endpoint name `nearai` is intentionally not a built-in LibreChat endpoint name. Omit the `provider` field to get LibreChat's OpenAI-compatible custom endpoint path, which is what this guide configures.
+
+### Reasoning models
+
+GLM 5.3 Flash is a reasoning model. It returns its thinking in a `reasoning_content` field, both in complete responses and as streamed deltas. The `customParams` block above tells LibreChat where to find that field so the thinking renders as a reasoning block instead of being discarded. Omit it and you lose the reasoning trace.
+
+### Title generation
+
+`titleModel` is called once per conversation. Because GLM 5.3 Flash is a reasoning model, each title costs a short reasoning pass. Set `titleModel: 'current_model'` to follow whichever model the conversation uses, or point it at a cheaper non-reasoning model from `/v1/models` if title cost matters at your volume.
 
 Add the key to `.env` in the same project root:
 
@@ -98,16 +113,16 @@ The primary refresh path is manual because this guide keeps a short, explicit mo
 3. Add it under `models.default` in `librechat.yaml`.
 4. Restart LibreChat so the endpoint selector reads the updated config.
 
-LibreChat's custom endpoint reference also documents `models.fetch: true` for OpenAI-compatible custom endpoints. If you want LibreChat to try `GET /v1/models`, add `fetch: true` under `models` after you confirm the curl check works in your environment:
+LibreChat's custom endpoint reference also documents `models.fetch: true` for OpenAI-compatible custom endpoints. NEAR AI Cloud serves `GET /v1/models` without authentication, so fetching works:
 
 ```yaml
 models:
   default:
-    - 'z-ai/glm-5.2'
+    - 'z-ai/glm-5.3-flash'
   fetch: true
 ```
 
-Keep `models.default` populated even when using fetch. LibreChat uses the default list as the fallback if fetching is slow or fails.
+Fetching returns every model on the gateway, 50+ of them, including embedding and reranker models that are not chat models, so stay with the manual list if you want a short endpoint selector. Either way, keep `models.default` populated: LibreChat falls back to it when fetching is slow or fails.
 
 ## Quick test
 
@@ -118,24 +133,28 @@ curl https://cloud-api.near.ai/v1/chat/completions \
   -H "Authorization: Bearer $NEARAI_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
-    "model": "z-ai/glm-5.2",
+    "model": "z-ai/glm-5.3-flash",
     "messages": [
       {"role": "user", "content": "Reply with only: near-ai-ok"}
     ],
-    "max_tokens": 20
+    "max_tokens": 256
   }'
 ```
 
+Keep `max_tokens` generous on reasoning models. GLM 5.3 Flash spends its first tokens on `reasoning_content`, so a tight limit returns `"content": null` with `"finish_reason": "length"` and looks like a failure when the request actually succeeded.
+
 If curl fails, fix the NEAR AI Cloud key, model ID, or network path before changing LibreChat settings.
 
 ## Troubleshooting
 
 | Symptom | Likely cause | Fix |
 | --- | --- | --- |
-| model not listed | `librechat.yaml` was not mounted, LibreChat was not restarted, or `z-ai/glm-5.2` is missing from `models.default`. | Confirm the Docker mount points to `/app/librechat.yaml`, run `docker compose logs api` for config errors, add the exact model ID under `models.default`, and restart LibreChat. |
+| model not listed | `librechat.yaml` was not mounted, LibreChat was not restarted, or `z-ai/glm-5.3-flash` is missing from `models.default`. | Confirm the Docker mount points to `/app/librechat.yaml`, run `docker compose logs api` for config errors, add the exact model ID under `models.default`, and restart LibreChat. |
 | `401` | `NEARAI_API_KEY` is missing from `.env`, the API container did not reload the environment, or the key is invalid. | Add `NEARAI_API_KEY=...` to `.env`, restart LibreChat, and rerun the curl smoke test without logging the key. |
 | Wrong base URL includes `/chat/completions` | The full curl request URL was pasted into `baseURL`. | Set `baseURL: 'https://cloud-api.near.ai/v1'`. Use `/chat/completions` only in full request URLs such as the curl smoke test. |
 | Endpoint not visible | The custom endpoint name conflicts with a built-in endpoint, YAML parsing failed, or the config file is in the wrong directory. | Keep `name: 'nearai'`, validate the YAML, make sure the file is in the LibreChat project root, and check `docker compose logs api`. |
+| Replies are empty or cut off mid-thought | A reasoning model consumed the output budget on `reasoning_content`. | Raise the model's max output in LibreChat, and confirm with the curl test at a higher `max_tokens`. |
+| The model thinks but the reasoning is never shown | `customParams.reasoningKey` is not set, so LibreChat does not know where NEAR AI puts the trace. | Add `reasoningFormat: reasoning_object` and `reasoningKey: reasoning_content` under `customParams`, then restart LibreChat. |
 | New NEAR AI model does not appear after release | LibreChat is reading the old manual list or cached endpoint config. | Recheck `/v1/models`, add the model ID under `models.default`, and restart LibreChat. If using `fetch: true`, keep the default fallback list and restart after changing fetch settings. |
 
 ## Related guides
@@ -150,9 +169,12 @@ If curl fails, fix the NEAR AI Cloud key, model ID, or network path before chang
 
 ## Sources Checked
 
-Sources checked on 2026-06-23:
+Sources checked on 2026-09-22:
 
 - [LibreChat Custom Endpoints](https://www.librechat.ai/docs/quick_start/custom_endpoints)
 - [LibreChat Custom Config](https://www.librechat.ai/docs/configuration/librechat_yaml)
 - [LibreChat Custom Endpoint Object Structure](https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/custom_endpoint)
+- [`librechat.example.yaml`](https://github.com/danny-avila/LibreChat/blob/main/librechat.example.yaml) — config `version`
+- [`docker-compose.override.yml.example`](https://github.com/danny-avila/LibreChat/blob/main/docker-compose.override.yml.example) — mount target
 - [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)
+- NEAR AI Cloud `GET /v1/models` and `POST /v1/chat/completions`

cloud/guides/integrations/opencode.mdx

@@ -0,0 +1,237 @@
+---
+title: "OpenCode"
+description: "Configure OpenCode to use NEAR AI Cloud as an OpenAI-compatible provider."
+---
+
+
+[OpenCode](https://opencode.ai/) is a terminal coding agent that resolves its providers from the public [models.dev](https://models.dev/) catalog. NEAR AI Cloud is already in that catalog as the `nearai` provider, so in the common case you do not write a provider block at all: set an API key, point `model` at a NEAR AI model, and OpenCode handles the rest.
+
+You only need a manual provider entry in two cases: the model you want is newer than the catalog, or you want to reach a model's TEE directly instead of going through the gateway. Both are covered below.
+
+## Prerequisites
+
+- OpenCode installed (verified against `1.18.31`).
+- A NEAR AI Cloud API key from the [NEAR AI Cloud Dashboard](https://cloud.near.ai/dashboard/organizations).
+
+Store the key in the environment variable the catalog declares for this provider, `NEARAI_API_KEY`:
+
+```bash
+export NEARAI_API_KEY="YOUR_NEAR_AI_API_KEY"
+```
+
+Alternatively, run `/connect` inside the OpenCode TUI, pick **NEAR AI Cloud**, and paste the key. OpenCode stores it in `~/.local/share/opencode/auth.json` so you do not need the environment variable.
+
+<Warning>
+Do not paste a literal key into `opencode.json`. Config files are frequently committed to source control. Use `NEARAI_API_KEY`, `/connect`, or the `{env:NEARAI_API_KEY}` substitution syntax shown below.
+</Warning>
+
+## Base URL
+
+The catalog already sets the gateway base URL for the `nearai` provider:
+
+```text
+https://cloud-api.near.ai/v1
+```
+
+You only set `options.baseURL` yourself when overriding it, for example to use a direct completions endpoint. Do not append `/chat/completions`; OpenCode adds the path when it calls the API.
+
+## Model ID
+
+OpenCode addresses a model as `<provider>/<model-id>`. Because NEAR AI model IDs already contain a slash, the resulting string has two:
+
+```text
+nearai/z-ai/glm-5.3-flash
+```
+
+This is expected. The provider is `nearai`; everything after the first slash is the NEAR AI model ID.
+
+Check [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery) for the current list.
+
+## Configure
+
+### Catalog models
+
+For any model already in the models.dev catalog, a `model` line is the whole configuration. Put it in `~/.config/opencode/opencode.json` for all projects, or `opencode.json` in a project root to override it there:
+
+```json opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "nearai/anthropic/claude-haiku-4-5"
+}
+```
+
+With `NEARAI_API_KEY` exported, `opencode` starts against NEAR AI Cloud. You can also skip the config file entirely and pick the model with `/models` in the TUI.
+
+`z-ai/glm-5.3-flash` is not in the catalog yet, so it needs the extra step in the next section. Use the check under [Refresh models](#refresh-models) to see which side of the line a given model falls on.
+
+### Models newer than the catalog
+
+The catalog lags NEAR AI Cloud releases. If `/models` does not list the model you want, declare it under `provider.nearai.models`. OpenCode merges this with the catalog entry, so you only supply what is missing:
+
+```json opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "nearai/z-ai/glm-5.3-flash",
+  "provider": {
+    "nearai": {
+      "models": {
+        "z-ai/glm-5.3-flash": {
+          "name": "GLM 5.3 Flash",
+          "tool_call": true,
+          "reasoning": true,
+          "limit": {
+            "context": 1048576,
+            "output": 131072
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Set `tool_call` and `reasoning` to match the model's `supported_features` in `/v1/models`, and set `limit` from its `context_length` and `max_output_length`. OpenCode uses these to decide whether to offer tool use and thinking-effort variants; a model with tool support left at the default will behave as though it has none.
+
+### Full provider block
+
+If your OpenCode version predates the catalog's `nearai` entry, define the provider outright:
+
+```json opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "nearai/z-ai/glm-5.3-flash",
+  "provider": {
+    "nearai": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "NEAR AI Cloud",
+      "options": {
+        "baseURL": "https://cloud-api.near.ai/v1",
+        "apiKey": "{env:NEARAI_API_KEY}"
+      },
+      "models": {
+        "z-ai/glm-5.3-flash": {
+          "name": "GLM 5.3 Flash",
+          "tool_call": true,
+          "reasoning": true,
+          "limit": {
+            "context": 1048576,
+            "output": 131072
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Trimming the model picker
+
+NEAR AI Cloud exposes 50+ models. OpenCode's documented `whitelist` and `blacklist` options keep `/models` short:
+
+```json opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "nearai": {
+      "whitelist": ["z-ai/glm-5.3-flash"]
+    }
+  }
+}
+```
+
+### Direct completions
+
+To bypass the gateway and connect straight to a model's TEE, override `baseURL` with that model's direct endpoint:
+
+```json opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "nearai/z-ai/glm-5.3-flash",
+  "provider": {
+    "nearai": {
+      "options": {
+        "baseURL": "https://glm-5-3-flash.completions.near.ai/v1"
+      }
+    }
+  }
+}
+```
+
+A direct endpoint serves exactly one model, so this override applies to the whole `nearai` provider. If you switch between models, keep the gateway base URL instead. See [Direct Completions](/cloud/private-inference#direct-completions).
+
+## Refresh models
+
+OpenCode does not call NEAR AI Cloud's `/v1/models`. Its picker comes from the models.dev catalog, so a newly released NEAR AI model appears only after the catalog updates.
+
+To check whether a model is available without a manual entry:
+
+```bash
+curl -s https://models.dev/api.json | jq -r '.nearai.models | keys[]'
+```
+
+Compare that against the live list:
+
+```bash
+curl -s https://cloud-api.near.ai/v1/models | jq -r '.data[].id'
+```
+
+Anything present in the second list but not the first needs a manual `provider.nearai.models` entry until the catalog catches up. `opencode models nearai` shows what OpenCode currently resolves, catalog plus your config combined.
+
+<Note>
+NEAR AI model IDs are aliased. Retired IDs often keep working because they resolve to their successor — `z-ai/glm-5.2` and `zai-org/GLM-5.1-FP8` both route to `z-ai/glm-5.3-flash` today. Prefer the canonical ID from `/v1/models`; an alias can be repointed without notice.
+</Note>
+
+## Quick test
+
+Verify the key, base URL, and model against the API before debugging OpenCode:
+
+```bash
+curl https://cloud-api.near.ai/v1/chat/completions \
+  -H "Authorization: Bearer $NEARAI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "z-ai/glm-5.3-flash",
+    "messages": [
+      {"role": "user", "content": "Reply with only: near-ai-ok"}
+    ],
+    "max_tokens": 256
+  }'
+```
+
+Keep `max_tokens` generous on reasoning models. GLM 5.3 Flash spends its first tokens on `reasoning_content`, so a tight limit returns `"content": null` with `"finish_reason": "length"` and looks like a failure.
+
+Once curl succeeds, test the same path through OpenCode:
+
+```bash
+opencode run "Reply with only: near-ai-ok"
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| model not listed: the model is missing from `/models` | The models.dev catalog is behind. Add it under `provider.nearai.models` as shown above, then confirm with `opencode models nearai`. |
+| Requests return `401` | `NEARAI_API_KEY` is not set in the shell that launched OpenCode, or no credential was stored. Export the variable, or run `/connect` and select NEAR AI Cloud. |
+| wrong base URL includes `/chat/completions` | Set `options.baseURL` to `https://cloud-api.near.ai/v1`. The `/chat/completions` path belongs only in full request URLs such as the curl test. |
+| OpenCode reports an unknown provider or model | The provider key must be `nearai`, and `model` must be `nearai/<model-id>` — including the slash inside the model ID, as in `nearai/z-ai/glm-5.3-flash`. |
+| The model replies but never calls tools | The manual model entry is missing `tool_call: true`. Catalog entries set this; hand-written ones default to off. |
+| Replies are empty or truncated mid-thought | A reasoning model hit the output limit. Raise `limit.output` in the model entry to match `max_output_length` from `/v1/models`. |
+| A direct completions base URL rejects the model | Each `*.completions.near.ai` endpoint serves one model. Confirm with `curl https://<endpoint>/v1/models` that it advertises the ID you configured. |
+
+## Related guides
+
+- [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)
+- [OpenAI Compatibility](/cloud/guides/openai-compatibility)
+- [Available Models](/cloud/models)
+- [Private Inference - Direct Completions](/cloud/private-inference#direct-completions)
+- [Goose](/cloud/guides/opencode-goose)
+- [Cline, Roo Code, and Kilo Code](/cloud/guides/integrations/cline-roo-kilo)
+
+## Sources Checked
+
+Sources checked on 2026-09-22, against OpenCode `1.18.31`:
+
+- [OpenCode providers](https://opencode.ai/docs/providers/)
+- [OpenCode config](https://opencode.ai/docs/config/)
+- [models.dev catalog](https://models.dev/) — `nearai` provider entry
+- NEAR AI Cloud `GET /v1/models`