docs: update for 6-provider architecture and reasoning primitives

Bring all top-level docs in line with the data-driven provider registry
that now supports 6 providers (openai, anthropic, gemini, ollama,
openrouter, together).

- README.md: lead description and Quick Links cover all 6 providers
- SETUP.md: add OpenRouter and Together AI setup sections, update
  parameter table and provider-specific defaults; note DeepSeek-R1
  thinking-tag behavior + max_tokens guidance
- USAGE.md: provider list in `set-provider` reference; add a
  reasoning/thinking example block (`set-thinking`,
  `set-reasoning-effort`, `set-thinking-budget`,
  `chat-with-thinking`); expand discovery examples
- API-REFERENCE.md: add quick-table rows for the 4 reasoning
  primitives, add a full Reasoning / Thinking Primitives section,
  extend Valid Providers list, readiness-check table, and
  provider-status example to include OpenRouter and Together
- EXAMPLES.md: include OpenRouter and Together in the
  compare-providers list; add Reasoning Models and OpenRouter
  one-key-many-models examples
- TESTING.md: document `demos/tests/config.txt.example` workflow,
  enumerate the 13 test procedures (including the two skip-aware
  provider-specific ones), list OPENROUTER_API_KEY / TOGETHER_API_KEY
  for future smoke-test secrets

Author: JNK234

docs/API-REFERENCE.md

@@ -11,12 +11,16 @@ The NetLogo Multi-LLM Extension provides a unified interface for multiple Large
 | `llm:chat text`                    | Chat          | Send synchronous chat message, returns response            |
 | `llm:chat-async text`              | Chat          | Send asynchronous chat message, returns awaitable reporter |
 | `llm:chat-with-template file vars` | Chat          | Send templated prompt with variable substitution           |
+| `llm:chat-with-thinking text`      | Chat          | Returns `[answer thinking]` for reasoning-capable models   |
 | `llm:choose prompt choices`        | Chat          | Force selection from provided options                      |
+| `llm:set-thinking bool`            | Reasoning     | Enable/disable reasoning mode for current provider         |
+| `llm:set-reasoning-effort level`   | Reasoning     | Set effort: `"low"`, `"medium"`, `"high"`                  |
+| `llm:set-thinking-budget n`        | Reasoning     | Token budget for thinking (min 1024; Anthropic + Gemini)   |
 | `llm:history`                      | History       | Get current agent's conversation history                   |
 | `llm:set-history list`             | History       | Set conversation history for current agent                 |
 | `llm:clear-history`                | History       | Clear conversation history for current agent               |
 | `llm:load-config filename`         | Configuration | Load settings from file                                    |
-| `llm:set-provider name`            | Configuration | Set active provider (openai, anthropic, gemini, ollama)    |
+| `llm:set-provider name`            | Configuration | Set active provider (openai, anthropic, gemini, ollama, openrouter, together) |
 | `llm:set-api-key key`              | Configuration | Set API key for current provider                           |
 | `llm:set-model name`               | Configuration | Set model to use for current provider                      |
 | `llm:providers`                    | Discovery     | List ready providers with configured keys/servers          |
@@ -70,6 +74,8 @@ llm:load-config "models/gpt4-config.txt"
 - `"anthropic"` - Anthropic Claude models
 - `"gemini"` - Google Gemini models
 - `"ollama"` - Local Ollama models
+- `"openrouter"` - OpenRouter (200+ models from many vendors via one API key)
+- `"together"` - Together AI (fast open-source model inference)
 
 **Example**:
 
@@ -229,6 +235,65 @@ set color read-from-string color-choice
 - Useful for agent decision-making in models
 - Maintains conversation context
 
+## Reasoning / Thinking Primitives
+
+For models that expose intermediate reasoning (Anthropic Claude, Google Gemini, Ollama qwen3/deepseek-r1, OpenRouter, Together AI). OpenAI o-series uses internal reasoning that the API does not return.
+
+### llm:chat-with-thinking
+
+**Syntax**: `llm:chat-with-thinking text`
+
+**Description**: Same as `llm:chat`, but returns both the final answer and the model's reasoning text as a 2-element list.
+
+**Returns**: `[answer thinking]` — both strings. `thinking` will be `""` if the provider/model does not expose reasoning tokens.
+
+**Example**:
+
+```netlogo
+llm:set-thinking true
+let result llm:chat-with-thinking "What is 17 * 23?"
+let answer   item 0 result
+let thinking item 1 result
+print (word "Answer: " answer)
+print (word "Reasoning: " thinking)
+```
+
+**Notes**:
+
+- Only the final answer is added to conversation history (not the thinking text).
+- For DeepSeek-R1 on Together AI, thinking is parsed from `<think>...</think>` tags in the content.
+- For Anthropic, OpenRouter, and Gemini, thinking comes from a dedicated reasoning field in the API response.
+
+### llm:set-thinking
+
+**Syntax**: `llm:set-thinking enabled?`
+
+**Description**: Enable or disable reasoning mode for the current provider. When enabled, the request includes provider-specific reasoning fields.
+
+**Parameters**:
+
+- `enabled?` (boolean): `true` to enable, `false` to disable
+
+### llm:set-reasoning-effort
+
+**Syntax**: `llm:set-reasoning-effort level`
+
+**Description**: Set the reasoning effort hint for models that support it (OpenAI o-series, OpenRouter, Together AI hybrid models).
+
+**Parameters**:
+
+- `level` (string): `"low"`, `"medium"`, or `"high"`
+
+### llm:set-thinking-budget
+
+**Syntax**: `llm:set-thinking-budget tokens`
+
+**Description**: Maximum tokens the model may spend on reasoning before producing the final answer. Used by Anthropic and Gemini.
+
+**Parameters**:
+
+- `tokens` (number): Minimum 1024. For Anthropic, the value is clamped to `[1024, max_tokens-1]`.
+
 ## History Management
 
 ### llm:history
@@ -320,12 +385,14 @@ if member? "ollama" llm:providers [
 
 **Readiness Checks**:
 
-| Provider  | Check Performed                                     |
-| --------- | --------------------------------------------------- |
-| OpenAI    | Has `openai_api_key` or `api_key` configured        |
-| Anthropic | Has `anthropic_api_key` or `api_key` configured     |
-| Gemini    | Has `gemini_api_key` or `api_key` configured        |
-| Ollama    | Server reachable at `ollama_base_url` (1s timeout)  |
+| Provider    | Check Performed                                       |
+| ----------- | ----------------------------------------------------- |
+| OpenAI      | Has `openai_api_key` or `api_key` configured          |
+| Anthropic   | Has `anthropic_api_key` or `api_key` configured       |
+| Gemini      | Has `gemini_api_key` or `api_key` configured          |
+| Ollama      | Server reachable at `ollama_base_url` (1s timeout)    |
+| OpenRouter  | Has `openrouter_api_key` configured                   |
+| Together AI | Has `together_api_key` configured                     |
 
 ### llm:providers-all
 
@@ -339,7 +406,7 @@ if member? "ollama" llm:providers [
 
 ```netlogo
 let all-providers llm:providers-all
-print all-providers  ; ["openai" "anthropic" "gemini" "ollama"]
+print all-providers  ; ["openai" "anthropic" "gemini" "ollama" "openrouter" "together"]
 ```
 
 ### llm:provider-status
@@ -359,7 +426,9 @@ print status
 ; [["openai" ["ready" true] ["has-key" true]]
 ;  ["anthropic" ["ready" false] ["has-key" false]]
 ;  ["gemini" ["ready" false] ["has-key" false]]
-;  ["ollama" ["ready" true] ["reachable" true] ["base-url" "http://localhost:11434"]]]
+;  ["ollama" ["ready" true] ["reachable" true] ["base-url" "http://localhost:11434"]]
+;  ["openrouter" ["ready" false] ["has-key" false]]
+;  ["together" ["ready" false] ["has-key" false]]]
 
 ; Check specific provider status
 foreach llm:provider-status [ provider-info ->
@@ -394,7 +463,7 @@ foreach llm:provider-status [ provider-info ->
 
 **Parameters**:
 
-- `provider-name` (string): Provider to get help for (`openai`, `anthropic`, `gemini`, `ollama`)
+- `provider-name` (string): Provider to get help for (`openai`, `anthropic`, `gemini`, `ollama`, `openrouter`, `together`)
 
 **Returns**: String - Multi-line setup instructions
 

docs/EXAMPLES.md

@@ -306,7 +306,7 @@ extensions [llm]
 globals [providers-list current-question]
 
 to setup
-  set providers-list ["openai" "anthropic" "gemini"]
+  set providers-list ["openai" "anthropic" "gemini" "openrouter" "together"]
   set current-question ""
 end
 
@@ -479,6 +479,56 @@ end
 
 ## Advanced Usage Examples
 
+### Reasoning Models — Show the Model's Work
+
+Use `llm:chat-with-thinking` to get both the final answer and the model's intermediate reasoning. Works with Anthropic Claude, Gemini 2.x, Ollama qwen3 / deepseek-r1, OpenRouter reasoning models, and Together AI's DeepSeek-R1.
+
+```netlogo
+extensions [llm]
+
+to setup-reasoning
+  llm:load-config "config.txt"        ;; e.g. provider=together, model=deepseek-ai/DeepSeek-R1
+  llm:set-thinking true
+  llm:set-reasoning-effort "high"     ;; OpenAI o-series + OpenRouter + Together hybrid
+  llm:set-thinking-budget 4096        ;; Anthropic + Gemini
+end
+
+to ask-with-reasoning [ question ]
+  let result llm:chat-with-thinking question
+  let answer   item 0 result
+  let thinking item 1 result
+  print (word "Q: " question)
+  print (word "Reasoning: " thinking)
+  print (word "Answer: " answer)
+end
+
+;; ask-with-reasoning "If a train leaves Chicago at 3pm going 60 mph, ..."
+```
+
+Note: bump `max_tokens` to 2000+ in your config for reasoning models; they often spend most of their token budget on the thinking phase before producing the final answer.
+
+### OpenRouter — One Key, Many Models
+
+Switch between vendors without juggling separate API keys:
+
+```netlogo
+extensions [llm]
+
+to setup
+  llm:set-provider "openrouter"
+  llm:set-api-key "sk-or-your-key"
+end
+
+to compare-vendors-via-openrouter
+  let prompt "Summarize agent-based modeling in one sentence."
+  foreach ["openai/gpt-4o-mini" "anthropic/claude-3.5-haiku" "meta-llama/llama-3.3-70b-instruct"] [ m ->
+    llm:set-model m
+    print (word m ": " llm:chat prompt)
+    llm:clear-history
+  ]
+end
+```
+
 ### Async Processing with Multiple Requests
 
 Handle multiple LLM requests simultaneously:

docs/README.md

@@ -1,6 +1,6 @@
 # NetLogo Multi-LLM Extension
 
-Unified LLM capabilities for NetLogo with multi-provider support (OpenAI, Anthropic/Claude, Google/Gemini, and local Ollama), per‑agent memory, async requests, and simple configuration.
+Unified LLM capabilities for NetLogo with multi-provider support — OpenAI, Anthropic/Claude, Google/Gemini, local Ollama, OpenRouter (200+ models via one key), and Together AI (fast open-source inference) — plus per‑agent memory, async requests, reasoning/thinking models, and simple configuration.
 
 ## Quick Links
 - Usage Guide: `docs/USAGE.md`
@@ -20,7 +20,7 @@ extensions [ llm ]
 ```
 llm:load-config "config.txt"
 ```
-See `docs/CONFIGURATION.md` for ready-to-copy examples (OpenAI, Anthropic, Gemini, Ollama). For inline setup:
+See `docs/CONFIGURATION.md` for ready-to-copy examples (OpenAI, Anthropic, Gemini, Ollama, OpenRouter, Together AI). For inline setup:
 ```
 llm:set-provider "openai"
 llm:set-api-key "sk-REPLACE_ME"

docs/SETUP.md

@@ -101,13 +101,63 @@ timeout_seconds=60
 
 **Pull command**: `ollama pull [model-name]`
 
+### OpenRouter (200+ models via one key)
+
+OpenRouter routes requests to many model vendors (OpenAI, Anthropic, Google, Meta, DeepSeek, etc.) through a single API.
+
+1. **Get API Key**: Visit [openrouter.ai/keys](https://openrouter.ai/keys)
+2. **Create config.txt**:
+```
+provider=openrouter
+model=openai/gpt-4o-mini
+openrouter_api_key=sk-or-your-key-here
+temperature=0.7
+max_tokens=1000
+```
+
+**Available Models** (vendor-prefixed):
+- `openai/gpt-4o-mini` - Fast, cost-effective (recommended)
+- `openai/gpt-4o` - GPT-4o through OpenRouter
+- `anthropic/claude-3.5-sonnet` - Claude 3.5 Sonnet
+- `anthropic/claude-3.5-haiku` - Fast Claude
+- `google/gemini-2.0-flash-exp` - Latest Gemini
+- `meta-llama/llama-3.3-70b-instruct` - Llama 3.3 70B
+- `deepseek/deepseek-r1` - Reasoning model
+
+Browse the full catalog: [openrouter.ai/models](https://openrouter.ai/models)
+
+### Together AI (open-source models)
+
+Together AI provides fast inference for open-source models (Llama, DeepSeek, Qwen, Mistral, Gemma) via an OpenAI-compatible API.
+
+1. **Get API Key**: Visit [api.together.ai/settings/api-keys](https://api.together.ai/settings/api-keys)
+2. **Create config.txt**:
+```
+provider=together
+model=meta-llama/Llama-3.3-70B-Instruct-Turbo
+together_api_key=your-together-key-here
+temperature=0.7
+max_tokens=1000
+```
+
+**Available Models** (vendor-prefixed):
+- `meta-llama/Llama-3.3-70B-Instruct-Turbo` - Fast Llama 3.3 (recommended)
+- `meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo` - Llama 3.1 70B
+- `deepseek-ai/DeepSeek-R1` - Reasoning model with `<think>` tag output
+- `Qwen/Qwen2.5-72B-Instruct-Turbo` - Qwen 2.5 72B
+- `mistralai/Mixtral-8x22B-Instruct-v0.1` - Mistral mixture-of-experts
+
+Browse the full catalog: [api.together.ai/models](https://api.together.ai/models)
+
+**Reasoning model note:** DeepSeek-R1 emits its thinking inside `<think>...</think>` tags (sometimes filling the entire response). Use `llm:chat-with-thinking` to get the answer and reasoning split out, and bump `max_tokens` to 2000+ so the model has room to finish its answer after thinking.
+
 ## Configuration Parameters
 
 ### Core Settings
 
 | Parameter | Description | Required | Default |
 |-----------|-------------|----------|---------|
-| `provider` | LLM provider (`openai`, `anthropic`, `gemini`, `ollama`) | Yes | - |
+| `provider` | LLM provider (`openai`, `anthropic`, `gemini`, `ollama`, `openrouter`, `together`) | Yes | - |
 | `model` | Model identifier | Yes | Provider-specific |
 | `api_key` | API authentication key | Yes* | - |
 | `temperature` | Response randomness (0.0-1.0) | No | 0.7 |
@@ -141,6 +191,16 @@ timeout_seconds=60
 - `max_tokens`: 2048
 - `timeout_seconds`: 60
 
+**OpenRouter**:
+- `base_url`: `https://openrouter.ai/api/v1`
+- `max_tokens`: 1000
+- API key config field: `openrouter_api_key`
+
+**Together AI**:
+- `base_url`: `https://api.together.xyz/v1`
+- `max_tokens`: 1000
+- API key config field: `together_api_key`
+
 ## Testing Your Setup
 
 1. **Create Test Model**:
@@ -173,7 +233,7 @@ end
 
 **"Provider not found"**
 - Check `provider=` line in config.txt
-- Verify spelling: `openai`, `anthropic`, `gemini`, `ollama`
+- Verify spelling: `openai`, `anthropic`, `gemini`, `ollama`, `openrouter`, `together`
 
 **"API key invalid"**
 - Verify API key is correct and active

docs/TESTING.md

@@ -82,9 +82,31 @@ These tests are **excluded from default `sbt test`** and from CI.
 Use `demos/tests/tests.nlogox` when you want to verify real providers end-to-end.
 
 These tests do require:
-- valid provider credentials for cloud providers, or
+- valid provider credentials for cloud providers (OpenAI, Anthropic, Gemini, OpenRouter, Together AI), or
 - a running Ollama server for local provider tests
 
+### Test setup
+
+1. Copy the template: `cp demos/tests/config.txt.example demos/tests/config.txt`
+2. Edit `config.txt`: set `provider=` to your chosen provider and replace the matching `*_api_key=REPLACE_ME` line with a real key. `config.txt` is gitignored, so the key stays local.
+3. Open `demos/tests/tests.nlogox` in NetLogo.
+4. In the Command Center: `run-all-tests`
+
+### What the suite covers
+
+The suite runs the same 13 test procedures regardless of provider, plus two provider-specific procedures that auto-skip if not applicable:
+
+- `test-providers` — registry has all 6 providers and `provider-help` returns text for each
+- `test-invalid-provider` — bogus provider name is rejected
+- `test-load-config` / `test-config-rollback` — config file loads cleanly and rolls back on failure
+- `test-sync-chat`, `test-async-chat`, `test-choose`, `test-history` — core chat flow
+- `test-thinking-config`, `test-chat-with-thinking` — reasoning primitives and `[answer thinking]` return shape
+- `test-openrouter-vendor-prefix` — vendor-prefixed model names (skips unless `provider=openrouter`)
+- `test-together-thinking` — DeepSeek-R1 `<think>` tag extraction (skips unless `provider=together` AND model contains "DeepSeek")
+- `test-reasoning-marker` — `[reasoning]` marker visible in `llm:list-models`
+
+To exercise everything, run the suite twice — once with `provider=openrouter`, once with `provider=together` (use `model=deepseek-ai/DeepSeek-R1` and `max_tokens=2000+` for the Together reasoning test).
+
 Suggested usage:
 - run automated tests first (`sbt test`)
 - run manual integration checks before releases or when changing provider adapters
@@ -125,5 +147,5 @@ For cloud-provider smoke tests you will need real API keys in CI secrets.
 
 Typical setup later:
 - separate workflow (manual trigger and/or nightly schedule)
-- secrets like `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`
+- secrets like `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`, `TOGETHER_API_KEY`
 - not required for normal PR merges (to avoid flaky/costly gating)