@formthefog/stratus 2026.2.20 → 2026.3.19

package/README.md

@@ -10,12 +10,16 @@ Integrate Stratus V3 (X1-AC), a state-of-the-art action-conditioned JEPA (Joint-
 
 ## Features
 
-- **Model Provider**: Use Stratus models (GPT-4o or Claude Sonnet 4 backends) for agent conversations
+- **Zero-Config**: Works out of the box with Formation pooled keys — no API key needed
+- **2050+ Models**: Dynamic discovery via OpenRouter — OpenAI, Anthropic, Google, and more
+- **Model Provider**: Use Stratus models for agent conversations with predictive planning
 - **Embeddings Tool**: Generate 768-dimensional semantic state embeddings
-- **Rollout Tool**: Multi-step task planning with action sequence prediction
-- **Secure**: API key authentication with automatic validation
+- **Rollout Tool**: Multi-step task planning via Policy Head v3 (94.4% accuracy)
+- **BYOK Support**: Bring your own provider keys (`openai_key`, `anthropic_key`, `gemini_key`) for zero-markup usage
 - **Opt-in Tools**: Tools are optional and require explicit allowlisting
 
+> See [SECURITY.md](./SECURITY.md) for a full accounting of credentials accessed, network calls made, and files written.
+
 ## Support
 
 - **Documentation**: [https://stratus.run/docs](https://stratus.run/docs)
@@ -24,7 +28,7 @@ Integrate Stratus V3 (X1-AC), a state-of-the-art action-conditioned JEPA (Joint-
 
 ## Installation
 
-### Quick Start (3 Steps) ✨
+### Quick Start (2 Steps) ✨
 
 > **Note:** This plugin does NOT have an automatic postinstall script. You must run setup manually.
 
@@ -39,15 +43,23 @@ openclaw plugins install @formthefog/stratus
 /stratus verify
 ```
 
-**That's it!** The `/stratus setup` command handles:
-- ✅ API key configuration
+**That's it!** No API key required — Formation pooled keys give you instant access to all 2050+ models.
+
+The `/stratus setup` command handles:
+- ✅ Zero-config auth via Formation pool (or BYOK if you have a key)
 - ✅ OpenClaw config updates
 - ✅ Auth profile creation
-- ✅ Model registration
+- ✅ Dynamic model registration
 - ✅ Gateway restart prompt
 
 **No manual config editing required!** 🧈
 
+> **Optional — BYOK (no markup):** Set `STRATUS_API_KEY` to bypass the Formation pool:
+> ```bash
+> export STRATUS_API_KEY=stratus_sk_your_key_here
+> ```
+> Then re-run `/stratus setup`.
+
 > **Tip:** Once installed, you can also access Stratus models with `/model stratus` in chat.
 
 ---
@@ -61,6 +73,7 @@ Use these slash commands in any OpenClaw chat (TUI, Telegram, Discord, etc.):
 | `/stratus` | Show help |
 | `/stratus setup` | Interactive configuration wizard |
 | `/stratus verify` | Verify plugin is configured correctly |
+| `/stratus models` | List all available models (live from API) |
 
 ---
 
@@ -68,11 +81,11 @@ Use these slash commands in any OpenClaw chat (TUI, Telegram, Discord, etc.):
 
 The interactive setup command will:
 
-1. ✅ Prompt for your Stratus API key
+1. ✅ Detect auth mode (BYOK if `STRATUS_API_KEY` is set, Formation pool otherwise)
 2. ✅ Update OpenClaw configuration
 3. ✅ Configure authentication profiles
-4. ✅ Add model aliases
-5. ✅ (Optional) Add environment variables to your shell config
+4. ✅ Dynamically register all available models from the API
+5. ✅ Report auth mode and markup status
 
 ---
 
@@ -151,23 +164,41 @@ Edit `~/.openclaw/openclaw.json`:
 ```json
 {
   "plugins": {
-    "stratus": {
-      "enabled": true,
-      "apiKey": "${STRATUS_API_KEY}",
-      "baseUrl": "https://api.stratus.run",
-      "provider": {
+    "entries": {
+      "stratus": {
         "enabled": true,
-        "defaultModel": "stratus-x1ac-base-claude-sonnet-4-5"
-      },
-      "tools": {
-        "embeddings": { "enabled": true },
-        "rollout": { "enabled": true }
+        "config": {
+          "apiKey": "${STRATUS_API_KEY}",
+          "baseUrl": "https://api.stratus.run",
+          "inlineKeys": {
+            "openai_key": "${OPENAI_API_KEY}",
+            "anthropic_key": "${ANTHROPIC_API_KEY}",
+            "gemini_key": "${GOOGLE_API_KEY}"
+          },
+          "provider": {
+            "enabled": true,
+            "defaultModel": "stratus-x1ac-base-claude-sonnet-4-5"
+          },
+          "tools": {
+            "embeddings": { "enabled": true },
+            "rollout": { "enabled": true }
+          }
+        }
       }
     }
   }
 }
 ```
 
+> **Note:** All keys are optional. Without any keys, Formation pooled keys are used automatically (25% markup). Inline provider keys (`openai_key`, `anthropic_key`, `gemini_key`) let you BYOK for specific providers while using the pool for others.
+
+> **Important:** OpenClaw's plugin config schema requires plugin-specific settings
+> to be nested under a `config` key within `plugins.entries.<id>`. Only `enabled`
+> and `config` are valid top-level keys per entry. Placing keys like `apiKey` or
+> `tools` at the top level will cause a config validation error and prevent the
+> gateway from starting.
+```
+
 ## Usage
 
 ### 1. Use Stratus as a Model Provider
@@ -188,9 +219,9 @@ openclaw agent --model stratus/stratus-x1ac-small-claude-haiku-4-5 \
   "Quick question: what is JEPA?"
 ```
 
-**Available Models: 75 Total**
+**Available Models: Dynamic (2050+ models)**
 
-The plugin registers all 75 Stratus chat completion models:
+Models are fetched live from the Stratus API on startup via OpenRouter dynamic discovery and refreshed automatically. Run `/stratus models` to see the current full list. The plugin supports all models returned by the API.
 
 **Model Format:** `stratus-x1ac-{size}-{llm}`
 
@@ -206,9 +237,12 @@ The plugin registers all 75 Stratus chat completion models:
 
 **Anthropic LLMs (Claude 4.x):**
 
+- `claude-sonnet-4-6` - Claude 4.6 Sonnet (latest)
+- `claude-opus-4-6` - Claude 4.6 Opus (latest, high performance)
 - `claude-sonnet-4-5` - Claude 4.5 Sonnet (recommended)
 - `claude-opus-4-5` - Claude 4.5 Opus
 - `claude-haiku-4-5` - Claude 4.5 Haiku (fast)
+- `claude-opus-4-1` - Claude 4.1 Opus
 - `claude-sonnet-4` - Claude 4 Sonnet
 - `claude-opus-4` - Claude 4 Opus
 
@@ -216,11 +250,20 @@ The plugin registers all 75 Stratus chat completion models:
 
 - `claude-3-7-sonnet`, `claude-3-5-sonnet`, `claude-3-opus`, `claude-3-sonnet`, `claude-3-haiku`
 
+**Google LLMs:**
+
+- `gemini-2.0-flash` - Gemini 2.0 Flash (1M context)
+- `gemini-1.5-pro` - Gemini 1.5 Pro (2M context)
+- `gemini-1.5-flash` - Gemini 1.5 Flash (1M context)
+- `gemini-pro` - Gemini Pro
+
 **Examples:**
 
 - `stratus/stratus-x1ac-base-claude-sonnet-4-5` (recommended)
+- `stratus/stratus-x1ac-base-claude-sonnet-4-6` (latest Claude)
 - `stratus/stratus-x1ac-base-gpt-4o`
-- `stratus/stratus-x1ac-large-claude-opus-4-5` (high performance)
+- `stratus/stratus-x1ac-base-gemini-2.0-flash` (1M context window)
+- `stratus/stratus-x1ac-large-claude-opus-4-6` (high performance)
 - `stratus/stratus-x1ac-small-gpt-4o-mini` (development/testing)
 
 ### 2. Use Stratus Tools
@@ -404,17 +447,9 @@ Tools are **opt-in only**:
 
 ### Quick Fixes
 
-#### "Stratus API key not configured"
-
-**Solution**:
-
-```bash
-export STRATUS_API_KEY=stratus_sk_live_your_key_here
-```
-
 #### "Invalid Stratus API key format"
 
-**Solution**: Verify your API key from stratus.run starts with `stratus_sk_`.
+**Solution**: If you set `STRATUS_API_KEY`, verify it starts with `stratus_sk_`. Or remove it entirely to use Formation pool (zero-config).
 
 #### "Tool not available"
 
@@ -460,18 +495,32 @@ This follows UNIX philosophy: clean separation, composable interfaces, transpare
 
 ### Configuration Schema
 
+OpenClaw plugin entries use `{ enabled, config }` at the top level. The `config`
+object holds all plugin-specific settings:
+
 ```typescript
+// What OpenClaw stores in plugins.entries.stratus
+interface PluginEntryConfig {
+  enabled?: boolean;
+  config?: StratusPluginConfig;
+}
+
+// Plugin-specific config (nested under "config" key)
 interface StratusPluginConfig {
-  enabled: boolean; // Enable plugin
-  apiKey: string; // API key (or env var)
-  baseUrl: string; // API base URL
-  provider: {
-    enabled: boolean; // Enable provider registration
-    defaultModel: string; // Default model
+  apiKey?: string;   // API key (optional — Formation pool used as fallback)
+  baseUrl?: string;  // API base URL
+  inlineKeys?: {     // BYOK keys passed per-request
+    openai_key?: string;
+    anthropic_key?: string;
+    gemini_key?: string;  // Also sent as X-Google-Key header
+  };
+  provider?: {
+    enabled?: boolean;     // Enable provider registration
+    defaultModel?: string; // Default model
   };
-  tools: {
-    embeddings: { enabled: boolean };
-    rollout: { enabled: boolean };
+  tools?: {
+    embeddings?: { enabled?: boolean };
+    rollout?: { enabled?: boolean };
   };
 }
 ```

package/SECURITY.md

@@ -0,0 +1,85 @@
+# Security Policy
+
+## What This Plugin Does
+
+`@formthefog/stratus` is an OpenClaw plugin that integrates the Stratus X1 world model API. This document provides a transparent accounting of all security-relevant behavior.
+
+---
+
+## Credentials
+
+**What is accessed:**
+- `STRATUS_API_KEY` — read from environment or OpenClaw config (`plugins.stratus.apiKey`). **Optional** — if not set, Formation pooled keys are used automatically.
+- `OPENAI_API_KEY` — optional, forwarded as inline BYOK key in request body
+- `ANTHROPIC_API_KEY` — optional, forwarded as inline BYOK key in request body
+- `GOOGLE_API_KEY` — optional, forwarded as inline BYOK key in request body and as `X-Google-Key` header
+
+**What is validated:**
+- If `STRATUS_API_KEY` is present, it must match the format `stratus_sk_*` — requests with malformed keys are rejected locally, no network call is made
+- If no key is present, the plugin operates in Formation pool mode (zero-config, 25% markup)
+
+**What is written to disk:**
+- During setup, the auth profile is stored in `~/.openclaw/agents/main/agent/auth-profiles.json`
+- This is the standard OpenClaw credential store, equivalent in scope to `~/.aws/credentials` or `~/.npmrc`
+- A timestamped backup of any existing file is created before writing
+- Keys are never logged, printed, or written anywhere else by this plugin
+
+**What is never accessed:**
+- `~/.ssh` or any SSH keys or known_hosts — nothing in this plugin reads or touches SSH paths
+- Other environment variables beyond `STRATUS_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `STRATUS_BASE_URL`, and `SHELL`
+- Browser storage, keychains, or system credential managers
+
+---
+
+## Network
+
+**Outbound endpoints:**
+| Endpoint | When | What is sent |
+|---|---|---|
+| `https://api.stratus.run/v1/embeddings` | `stratus_embeddings` tool call | `Authorization: Bearer <key>` (if set), text input, optional inline keys |
+| `https://api.stratus.run/v1/rollout` | `stratus_rollout` tool call | `Authorization: Bearer <key>` (if set), goal + state, optional inline keys |
+| `https://api.stratus.run/v1/models` | Plugin startup / `/stratus models` | `Authorization: Bearer <key>` (if set) |
+
+**Headers sent:**
+- `Authorization: Bearer <key>` — only when `STRATUS_API_KEY` is configured
+- `X-Google-Key: <key>` — only when a Google/Gemini key is configured
+- `Content-Type: application/json` — on all POST requests
+
+**Inline key fields in request body:**
+- `openai_key`, `anthropic_key`, `gemini_key` — only when corresponding environment variables or config values are set
+
+**What is never done:**
+- No calls to any endpoint other than `api.stratus.run`
+- No telemetry, analytics, or usage reporting
+- No data is sent to third parties
+- All connections are HTTPS-only
+
+Data handling is governed by the [Stratus privacy policy](https://stratus.run/privacy).
+
+---
+
+## File System
+
+**Files read during setup/verify:**
+- `~/.openclaw/openclaw.json` — OpenClaw's own config, to add the Stratus provider entry
+- `~/.openclaw/agents/main/agent/auth-profiles.json` — OpenClaw's own auth store, to add Stratus credentials
+- `~/Library/LaunchAgents/ai.openclaw.gateway.plist` — macOS only, if the user explicitly opts in during `install.sh`
+
+**Files written during setup:**
+- Same paths as above, plus timestamped `.backup-*` copies before any modification
+
+**What is never touched:**
+- No files outside `~/.openclaw/` or the LaunchAgent plist
+- No `/etc/`, `/usr/`, `/Library/` (system paths)
+- No other dotfiles or home directory contents
+
+---
+
+## Reporting a Vulnerability
+
+If you discover a security issue, please report it privately:
+
+- Email: security@stratus.run
+- GitHub: [open a private security advisory](https://github.com/formthefog/openclaw-stratus-x1-plugin/security/advisories/new)
+
+Please do not open a public issue for security vulnerabilities. We aim to respond within 72 hours.

package/TROUBLESHOOTING.md

@@ -132,9 +132,9 @@ Implement Option 1 (plugin-level role mapping) as it provides maximum compatibil
 
 ### "Stratus API key not configured"
 
-**Cause**: No API key found in config or environment.
+**Note**: As of March 2026, an API key is **no longer required**. The plugin uses Formation pooled keys by default (zero-config, 25% markup). This error should no longer appear.
 
-**Solution**:
+If you want BYOK (no markup), set your key:
 
 ```bash
 export STRATUS_API_KEY=stratus_sk_live_your_key_here