feat(claude): support custom model registry

packages/docs-web/src/content/docs/getting-started/ai-assistants.md

@@ -129,6 +129,48 @@ assistants:
 
 The `settingSources` option controls which `CLAUDE.md`, skill, command, and agent files the Claude Code SDK loads. The default is `['project', 'user']`, which loads both the project-level `<cwd>/.claude/` and your personal `~/.claude/`. Set it to `['project']` if you want to scope a workflow to project-only resources.
 
+### Custom Claude-Compatible Providers
+
+Claude workflows can reference custom provider models by friendly aliases. Define them in `~/.archon/claude-models.json`, then use `provider/name` in `.archon/config.yaml` or workflow node `model` fields.
+
+```json
+{
+  "providers": {
+    "gateway": {
+      "baseUrl": "https://llm-gateway.example.com",
+      "apiKey": "CLAUDE_GATEWAY_API_KEY",
+      "headers": {
+        "X-Team": "platform",
+        "X-Workspace-Token": "CLAUDE_GATEWAY_WORKSPACE_TOKEN"
+      },
+      "models": [
+        {
+          "id": "openai/gpt-5.4",
+          "name": "gpt",
+          "reasoning": true
+        },
+        {
+          "id": "zai-org/glm-5",
+          "name": "glm"
+        }
+      ]
+    }
+  }
+}
+```
+
+Then configure Claude to use the alias:
+
+```yaml
+assistants:
+  claude:
+    model: gateway/gpt
+```
+
+Use `apiKey` for providers that expect `ANTHROPIC_API_KEY`, or `authToken` for providers that expect a bearer token via `ANTHROPIC_AUTH_TOKEN`. `baseUrl` maps to `ANTHROPIC_BASE_URL`, and `headers` are sent through `ANTHROPIC_CUSTOM_HEADERS`.
+
+For `baseUrl`, `apiKey`, `authToken`, and header values, Archon first checks whether the configured value is an environment variable name. If it exists, Archon uses the environment value; otherwise it uses the configured value literally. For example, `"apiKey": "CLAUDE_GATEWAY_API_KEY"` reads `process.env.CLAUDE_GATEWAY_API_KEY` when it is set.
+
 ### Set as Default (Optional)
 
 If you want Claude to be the default AI assistant for new conversations without codebase context, set this environment variable:

packages/docs-web/src/content/docs/reference/configuration.md

@@ -96,6 +96,53 @@ concurrency:
 
 ```
 
+### Claude Custom Models
+
+For Claude-compatible gateways or local providers, create `~/.archon/claude-models.json`. This file is separate from `config.yaml` so provider credentials and model catalogs can be managed without editing workflow YAML.
+
+```json
+{
+  "providers": {
+    "gateway": {
+      "baseUrl": "https://llm-gateway.example.com",
+      "apiKey": "CLAUDE_GATEWAY_API_KEY",
+      "headers": {
+        "X-Team": "platform",
+        "X-Workspace-Token": "CLAUDE_GATEWAY_WORKSPACE_TOKEN"
+      },
+      "models": [
+        {
+          "id": "openai/gpt-5.4",
+          "name": "gpt",
+          "reasoning": true
+        }
+      ]
+    }
+  }
+}
+```
+
+Use the alias in config or workflow nodes:
+
+```yaml
+assistants:
+  claude:
+    model: gateway/gpt
+```
+
+Field mapping:
+
+| Field | Claude Code env |
+|---|---|
+| `baseUrl` | `ANTHROPIC_BASE_URL` |
+| `apiKey` | `ANTHROPIC_API_KEY` |
+| `authToken` | `ANTHROPIC_AUTH_TOKEN` |
+| `headers` | `ANTHROPIC_CUSTOM_HEADERS` |
+
+For `baseUrl`, `apiKey`, `authToken`, and header values, Archon first checks whether the configured value is an environment variable name. If it exists, Archon uses the environment value; otherwise it uses the configured value literally. For example, `"apiKey": "CLAUDE_GATEWAY_API_KEY"` reads `process.env.CLAUDE_GATEWAY_API_KEY` when it is set.
+
+An example file is available at `packages/providers/src/claude/claude-models.json.example`. It contains placeholders only; do not commit real gateway URLs, API keys, or tokens.
+
 ## Repository Configuration
 
 Create `.archon/config.yaml` in any repository for project-specific settings:

packages/providers/package.json

@@ -18,7 +18,7 @@
     "./registry": "./src/registry.ts"
   },
   "scripts": {
-    "test": "bun test src/claude/provider.test.ts && bun test src/codex/provider.test.ts && bun test src/registry.test.ts && bun test src/codex/binary-guard.test.ts && bun test src/codex/binary-resolver.test.ts && bun test src/codex/binary-resolver-dev.test.ts && bun test src/claude/binary-resolver.test.ts && bun test src/claude/binary-resolver-dev.test.ts && bun test src/community/pi/model-ref.test.ts && bun test src/community/pi/config.test.ts && bun test src/community/pi/event-bridge.test.ts && bun test src/community/pi/options-translator.test.ts && bun test src/community/pi/session-resolver.test.ts && bun test src/community/pi/provider.test.ts && bun test src/community/pi/provider-lazy-load.test.ts",
+    "test": "bun test src/claude/model-registry.test.ts && bun test src/claude/provider.test.ts && bun test src/codex/provider.test.ts && bun test src/registry.test.ts && bun test src/codex/binary-guard.test.ts && bun test src/codex/binary-resolver.test.ts && bun test src/codex/binary-resolver-dev.test.ts && bun test src/claude/binary-resolver.test.ts && bun test src/claude/binary-resolver-dev.test.ts && bun test src/community/pi/model-ref.test.ts && bun test src/community/pi/config.test.ts && bun test src/community/pi/event-bridge.test.ts && bun test src/community/pi/options-translator.test.ts && bun test src/community/pi/session-resolver.test.ts && bun test src/community/pi/provider.test.ts && bun test src/community/pi/provider-lazy-load.test.ts",
     "type-check": "bun x tsc --noEmit"
   },
   "dependencies": {

packages/providers/src/claude/claude-models.json.example

@@ -0,0 +1,34 @@
+{
+  "providers": {
+    "gateway": {
+      "baseUrl": "https://llm-gateway.example.com",
+      "apiKey": "CLAUDE_GATEWAY_API_KEY",
+      "headers": {
+        "X-Team": "platform",
+        "X-Workspace-Token": "CLAUDE_GATEWAY_WORKSPACE_TOKEN"
+      },
+      "models": [
+        {
+          "id": "openai/gpt-5.4",
+          "name": "gpt",
+          "reasoning": true
+        },
+        {
+          "id": "zai-org/glm-5",
+          "name": "glm",
+          "reasoning": false
+        }
+      ]
+    },
+    "local": {
+      "baseUrl": "http://localhost:4000",
+      "authToken": "CLAUDE_LOCAL_GATEWAY_TOKEN",
+      "models": [
+        {
+          "id": "local/model-name",
+          "name": "local-model"
+        }
+      ]
+    }
+  }
+}