milaidy 1.0.0

package/docs/providers/moonshot.md

@@ -0,0 +1,142 @@
+---
+summary: "Configure Moonshot K2 vs Kimi Coding (separate providers + keys)"
+read_when:
+  - You want Moonshot K2 (Moonshot Open Platform) vs Kimi Coding setup
+  - You need to understand separate endpoints, keys, and model refs
+  - You want copy/paste config for either provider
+title: "Moonshot AI"
+---
+
+# Moonshot AI (Kimi)
+
+Moonshot provides the Kimi API with OpenAI-compatible endpoints. Configure the
+provider and set the default model to `moonshot/kimi-k2.5`, or use
+Kimi Coding with `kimi-coding/k2p5`.
+
+Current Kimi K2 model IDs:
+
+{/_ moonshot-kimi-k2-ids:start _/ && null}
+
+- `kimi-k2.5`
+- `kimi-k2-0905-preview`
+- `kimi-k2-turbo-preview`
+- `kimi-k2-thinking`
+- `kimi-k2-thinking-turbo`
+  {/_ moonshot-kimi-k2-ids:end _/ && null}
+
+```bash
+milaidy onboard --auth-choice moonshot-api-key
+```
+
+Kimi Coding:
+
+```bash
+milaidy onboard --auth-choice kimi-code-api-key
+```
+
+Note: Moonshot and Kimi Coding are separate providers. Keys are not interchangeable, endpoints differ, and model refs differ (Moonshot uses `moonshot/...`, Kimi Coding uses `kimi-coding/...`).
+
+## Config snippet (Moonshot API)
+
+```json5
+{
+  env: { MOONSHOT_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      model: { primary: "moonshot/kimi-k2.5" },
+      models: {
+        // moonshot-kimi-k2-aliases:start
+        "moonshot/kimi-k2.5": { alias: "Kimi K2.5" },
+        "moonshot/kimi-k2-0905-preview": { alias: "Kimi K2" },
+        "moonshot/kimi-k2-turbo-preview": { alias: "Kimi K2 Turbo" },
+        "moonshot/kimi-k2-thinking": { alias: "Kimi K2 Thinking" },
+        "moonshot/kimi-k2-thinking-turbo": { alias: "Kimi K2 Thinking Turbo" },
+        // moonshot-kimi-k2-aliases:end
+      },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      moonshot: {
+        baseUrl: "https://api.moonshot.ai/v1",
+        apiKey: "${MOONSHOT_API_KEY}",
+        api: "openai-completions",
+        models: [
+          // moonshot-kimi-k2-models:start
+          {
+            id: "kimi-k2.5",
+            name: "Kimi K2.5",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 256000,
+            maxTokens: 8192,
+          },
+          {
+            id: "kimi-k2-0905-preview",
+            name: "Kimi K2 0905 Preview",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 256000,
+            maxTokens: 8192,
+          },
+          {
+            id: "kimi-k2-turbo-preview",
+            name: "Kimi K2 Turbo",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 256000,
+            maxTokens: 8192,
+          },
+          {
+            id: "kimi-k2-thinking",
+            name: "Kimi K2 Thinking",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 256000,
+            maxTokens: 8192,
+          },
+          {
+            id: "kimi-k2-thinking-turbo",
+            name: "Kimi K2 Thinking Turbo",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 256000,
+            maxTokens: 8192,
+          },
+          // moonshot-kimi-k2-models:end
+        ],
+      },
+    },
+  },
+}
+```
+
+## Kimi Coding
+
+```json5
+{
+  env: { KIMI_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      model: { primary: "kimi-coding/k2p5" },
+      models: {
+        "kimi-coding/k2p5": { alias: "Kimi K2.5" },
+      },
+    },
+  },
+}
+```
+
+## Notes
+
+- Moonshot model refs use `moonshot/<modelId>`. Kimi Coding model refs use `kimi-coding/<modelId>`.
+- Override pricing and context metadata in `models.providers` if needed.
+- If Moonshot publishes different context limits for a model, adjust
+  `contextWindow` accordingly.
+- Use `https://api.moonshot.ai/v1` for the international endpoint, and `https://api.moonshot.cn/v1` for the China endpoint.

package/docs/providers/ollama.md

@@ -0,0 +1,223 @@
+---
+summary: "Run Milaidy with Ollama (local LLM runtime)"
+read_when:
+  - You want to run Milaidy with local models via Ollama
+  - You need Ollama setup and configuration guidance
+title: "Ollama"
+---
+
+# Ollama
+
+Ollama is a local LLM runtime that makes it easy to run open-source models on your machine. Milaidy integrates with Ollama's OpenAI-compatible API and can **auto-discover tool-capable models** when you opt in with `OLLAMA_API_KEY` (or an auth profile) and do not define an explicit `models.providers.ollama` entry.
+
+## Quick start
+
+1. Install Ollama: https://ollama.ai
+
+2. Pull a model:
+
+```bash
+ollama pull llama3.3
+# or
+ollama pull qwen2.5-coder:32b
+# or
+ollama pull deepseek-r1:32b
+```
+
+3. Enable Ollama for Milaidy (any value works; Ollama doesn't require a real key):
+
+```bash
+# Set environment variable
+export OLLAMA_API_KEY="ollama-local"
+
+# Or configure in your config file
+milaidy config set models.providers.ollama.apiKey "ollama-local"
+```
+
+4. Use Ollama models:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "ollama/llama3.3" },
+    },
+  },
+}
+```
+
+## Model discovery (implicit provider)
+
+When you set `OLLAMA_API_KEY` (or an auth profile) and **do not** define `models.providers.ollama`, Milaidy discovers models from the local Ollama instance at `http://127.0.0.1:11434`:
+
+- Queries `/api/tags` and `/api/show`
+- Keeps only models that report `tools` capability
+- Marks `reasoning` when the model reports `thinking`
+- Reads `contextWindow` from `model_info["<arch>.context_length"]` when available
+- Sets `maxTokens` to 10× the context window
+- Sets all costs to `0`
+
+This avoids manual model entries while keeping the catalog aligned with Ollama's capabilities.
+
+To see what models are available:
+
+```bash
+ollama list
+milaidy models list
+```
+
+To add a new model, simply pull it with Ollama:
+
+```bash
+ollama pull mistral
+```
+
+The new model will be automatically discovered and available to use.
+
+If you set `models.providers.ollama` explicitly, auto-discovery is skipped and you must define models manually (see below).
+
+## Configuration
+
+### Basic setup (implicit discovery)
+
+The simplest way to enable Ollama is via environment variable:
+
+```bash
+export OLLAMA_API_KEY="ollama-local"
+```
+
+### Explicit setup (manual models)
+
+Use explicit config when:
+
+- Ollama runs on another host/port.
+- You want to force specific context windows or model lists.
+- You want to include models that do not report tool support.
+
+```json5
+{
+  models: {
+    providers: {
+      ollama: {
+        // Use a host that includes /v1 for OpenAI-compatible APIs
+        baseUrl: "http://ollama-host:11434/v1",
+        apiKey: "ollama-local",
+        api: "openai-completions",
+        models: [
+          {
+            id: "llama3.3",
+            name: "Llama 3.3",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 8192,
+            maxTokens: 8192 * 10
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+If `OLLAMA_API_KEY` is set, you can omit `apiKey` in the provider entry and Milaidy will fill it for availability checks.
+
+### Custom base URL (explicit config)
+
+If Ollama is running on a different host or port (explicit config disables auto-discovery, so define models manually):
+
+```json5
+{
+  models: {
+    providers: {
+      ollama: {
+        apiKey: "ollama-local",
+        baseUrl: "http://ollama-host:11434/v1",
+      },
+    },
+  },
+}
+```
+
+### Model selection
+
+Once configured, all your Ollama models are available:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: {
+        primary: "ollama/llama3.3",
+        fallback: ["ollama/qwen2.5-coder:32b"],
+      },
+    },
+  },
+}
+```
+
+## Advanced
+
+### Reasoning models
+
+Milaidy marks models as reasoning-capable when Ollama reports `thinking` in `/api/show`:
+
+```bash
+ollama pull deepseek-r1:32b
+```
+
+### Model Costs
+
+Ollama is free and runs locally, so all model costs are set to $0.
+
+### Context windows
+
+For auto-discovered models, Milaidy uses the context window reported by Ollama when available, otherwise it defaults to `8192`. You can override `contextWindow` and `maxTokens` in explicit provider config.
+
+## Troubleshooting
+
+### Ollama not detected
+
+Make sure Ollama is running and that you set `OLLAMA_API_KEY` (or an auth profile), and that you did **not** define an explicit `models.providers.ollama` entry:
+
+```bash
+ollama serve
+```
+
+And that the API is accessible:
+
+```bash
+curl http://localhost:11434/api/tags
+```
+
+### No models available
+
+Milaidy only auto-discovers models that report tool support. If your model isn't listed, either:
+
+- Pull a tool-capable model, or
+- Define the model explicitly in `models.providers.ollama`.
+
+To add models:
+
+```bash
+ollama list  # See what's installed
+ollama pull llama3.3  # Pull a model
+```
+
+### Connection refused
+
+Check that Ollama is running on the correct port:
+
+```bash
+# Check if Ollama is running
+ps aux | grep ollama
+
+# Or restart Ollama
+ollama serve
+```
+
+## See Also
+
+- [Model Providers](/concepts/model-providers) - Overview of all providers
+- [Model Selection](/concepts/models) - How to choose models
+- [Configuration](/gateway/configuration) - Full config reference

package/docs/providers/openai.md

@@ -0,0 +1,62 @@
+---
+summary: "Use OpenAI via API keys or Codex subscription in Milaidy"
+read_when:
+  - You want to use OpenAI models in Milaidy
+  - You want Codex subscription auth instead of API keys
+title: "OpenAI"
+---
+
+# OpenAI
+
+OpenAI provides developer APIs for GPT models. Codex supports **ChatGPT sign-in** for subscription
+access or **API key** sign-in for usage-based access. Codex cloud requires ChatGPT sign-in.
+
+## Option A: OpenAI API key (OpenAI Platform)
+
+**Best for:** direct API access and usage-based billing.
+Get your API key from the OpenAI dashboard.
+
+### CLI setup
+
+```bash
+milaidy onboard --auth-choice openai-api-key
+# or non-interactive
+milaidy onboard --openai-api-key "$OPENAI_API_KEY"
+```
+
+### Config snippet
+
+```json5
+{
+  env: { OPENAI_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "openai/gpt-5.2" } } },
+}
+```
+
+## Option B: OpenAI Code (Codex) subscription
+
+**Best for:** using ChatGPT/Codex subscription access instead of an API key.
+Codex cloud requires ChatGPT sign-in, while the Codex CLI supports ChatGPT or API key sign-in.
+
+### CLI setup
+
+```bash
+# Run Codex OAuth in the wizard
+milaidy onboard --auth-choice openai-codex
+
+# Or run OAuth directly
+milaidy models auth login --provider openai-codex
+```
+
+### Config snippet
+
+```json5
+{
+  agents: { defaults: { model: { primary: "openai-codex/gpt-5.2" } } },
+}
+```
+
+## Notes
+
+- Model refs always use `provider/model` (see [/concepts/models](/concepts/models)).
+- Auth details + reuse rules are in [/concepts/oauth](/concepts/oauth).

package/docs/providers/opencode.md

@@ -0,0 +1,36 @@
+---
+summary: "Use OpenCode Zen (curated models) with Milaidy"
+read_when:
+  - You want OpenCode Zen for model access
+  - You want a curated list of coding-friendly models
+title: "OpenCode Zen"
+---
+
+# OpenCode Zen
+
+OpenCode Zen is a **curated list of models** recommended by the OpenCode team for coding agents.
+It is an optional, hosted model access path that uses an API key and the `opencode` provider.
+Zen is currently in beta.
+
+## CLI setup
+
+```bash
+milaidy onboard --auth-choice opencode-zen
+# or non-interactive
+milaidy onboard --opencode-zen-api-key "$OPENCODE_API_KEY"
+```
+
+## Config snippet
+
+```json5
+{
+  env: { OPENCODE_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "opencode/claude-opus-4-5" } } },
+}
+```
+
+## Notes
+
+- `OPENCODE_ZEN_API_KEY` is also supported.
+- You sign in to Zen, add billing details, and copy your API key.
+- OpenCode Zen bills per request; check the OpenCode dashboard for details.

package/docs/providers/openrouter.md

@@ -0,0 +1,37 @@
+---
+summary: "Use OpenRouter's unified API to access many models in Milaidy"
+read_when:
+  - You want a single API key for many LLMs
+  - You want to run models via OpenRouter in Milaidy
+title: "OpenRouter"
+---
+
+# OpenRouter
+
+OpenRouter provides a **unified API** that routes requests to many models behind a single
+endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
+
+## CLI setup
+
+```bash
+milaidy onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY"
+```
+
+## Config snippet
+
+```json5
+{
+  env: { OPENROUTER_API_KEY: "sk-or-..." },
+  agents: {
+    defaults: {
+      model: { primary: "openrouter/anthropic/claude-sonnet-4-5" },
+    },
+  },
+}
+```
+
+## Notes
+
+- Model refs are `openrouter/<provider>/<model>`.
+- For more model/provider options, see [/concepts/model-providers](/concepts/model-providers).
+- OpenRouter uses a Bearer token with your API key under the hood.

package/docs/providers/qwen.md

@@ -0,0 +1,53 @@
+---
+summary: "Use Qwen OAuth (free tier) in Milaidy"
+read_when:
+  - You want to use Qwen with Milaidy
+  - You want free-tier OAuth access to Qwen Coder
+title: "Qwen"
+---
+
+# Qwen
+
+Qwen provides a free-tier OAuth flow for Qwen Coder and Qwen Vision models
+(2,000 requests/day, subject to Qwen rate limits).
+
+## Enable the plugin
+
+```bash
+milaidy plugins enable qwen-portal-auth
+```
+
+Restart the Gateway after enabling.
+
+## Authenticate
+
+```bash
+milaidy models auth login --provider qwen-portal --set-default
+```
+
+This runs the Qwen device-code OAuth flow and writes a provider entry to your
+`models.json` (plus a `qwen` alias for quick switching).
+
+## Model IDs
+
+- `qwen-portal/coder-model`
+- `qwen-portal/vision-model`
+
+Switch models with:
+
+```bash
+milaidy models set qwen-portal/coder-model
+```
+
+## Reuse Qwen Code CLI login
+
+If you already logged in with the Qwen Code CLI, Milaidy will sync credentials
+from `~/.qwen/oauth_creds.json` when it loads the auth store. You still need a
+`models.providers.qwen-portal` entry (use the login command above to create one).
+
+## Notes
+
+- Tokens auto-refresh; re-run the login command if refresh fails or access is revoked.
+- Default base URL: `https://portal.qwen.ai/v1` (override with
+  `models.providers.qwen-portal.baseUrl` if Qwen provides a different endpoint).
+- See [Model providers](/concepts/model-providers) for provider-wide rules.

package/docs/providers/synthetic.md

@@ -0,0 +1,99 @@
+---
+summary: "Use Synthetic's Anthropic-compatible API in Milaidy"
+read_when:
+  - You want to use Synthetic as a model provider
+  - You need a Synthetic API key or base URL setup
+title: "Synthetic"
+---
+
+# Synthetic
+
+Synthetic exposes Anthropic-compatible endpoints. Milaidy registers it as the
+`synthetic` provider and uses the Anthropic Messages API.
+
+## Quick setup
+
+1. Set `SYNTHETIC_API_KEY` (or run the wizard below).
+2. Run onboarding:
+
+```bash
+milaidy onboard --auth-choice synthetic-api-key
+```
+
+The default model is set to:
+
+```
+synthetic/hf:MiniMaxAI/MiniMax-M2.1
+```
+
+## Config example
+
+```json5
+{
+  env: { SYNTHETIC_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.1" },
+      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.1": { alias: "MiniMax M2.1" } },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      synthetic: {
+        baseUrl: "https://api.synthetic.new/anthropic",
+        apiKey: "${SYNTHETIC_API_KEY}",
+        api: "anthropic-messages",
+        models: [
+          {
+            id: "hf:MiniMaxAI/MiniMax-M2.1",
+            name: "MiniMax M2.1",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 192000,
+            maxTokens: 65536,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+Note: Milaidy's Anthropic client appends `/v1` to the base URL, so use
+`https://api.synthetic.new/anthropic` (not `/anthropic/v1`). If Synthetic changes
+its base URL, override `models.providers.synthetic.baseUrl`.
+
+## Model catalog
+
+All models below use cost `0` (input/output/cache).
+
+| Model ID                                               | Context window | Max tokens | Reasoning | Input        |
+| ------------------------------------------------------ | -------------- | ---------- | --------- | ------------ |
+| `hf:MiniMaxAI/MiniMax-M2.1`                            | 192000         | 65536      | false     | text         |
+| `hf:moonshotai/Kimi-K2-Thinking`                       | 256000         | 8192       | true      | text         |
+| `hf:zai-org/GLM-4.7`                                   | 198000         | 128000     | false     | text         |
+| `hf:deepseek-ai/DeepSeek-R1-0528`                      | 128000         | 8192       | false     | text         |
+| `hf:deepseek-ai/DeepSeek-V3-0324`                      | 128000         | 8192       | false     | text         |
+| `hf:deepseek-ai/DeepSeek-V3.1`                         | 128000         | 8192       | false     | text         |
+| `hf:deepseek-ai/DeepSeek-V3.1-Terminus`                | 128000         | 8192       | false     | text         |
+| `hf:deepseek-ai/DeepSeek-V3.2`                         | 159000         | 8192       | false     | text         |
+| `hf:meta-llama/Llama-3.3-70B-Instruct`                 | 128000         | 8192       | false     | text         |
+| `hf:meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 524000         | 8192       | false     | text         |
+| `hf:moonshotai/Kimi-K2-Instruct-0905`                  | 256000         | 8192       | false     | text         |
+| `hf:openai/gpt-oss-120b`                               | 128000         | 8192       | false     | text         |
+| `hf:Qwen/Qwen3-235B-A22B-Instruct-2507`                | 256000         | 8192       | false     | text         |
+| `hf:Qwen/Qwen3-Coder-480B-A35B-Instruct`               | 256000         | 8192       | false     | text         |
+| `hf:Qwen/Qwen3-VL-235B-A22B-Instruct`                  | 250000         | 8192       | false     | text + image |
+| `hf:zai-org/GLM-4.5`                                   | 128000         | 128000     | false     | text         |
+| `hf:zai-org/GLM-4.6`                                   | 198000         | 128000     | false     | text         |
+| `hf:deepseek-ai/DeepSeek-V3`                           | 128000         | 8192       | false     | text         |
+| `hf:Qwen/Qwen3-235B-A22B-Thinking-2507`                | 256000         | 8192       | true      | text         |
+
+## Notes
+
+- Model refs use `synthetic/<modelId>`.
+- If you enable a model allowlist (`agents.defaults.models`), add every model you
+  plan to use.
+- See [Model providers](/concepts/model-providers) for provider rules.