@useorgx/openclaw-plugin 0.4.4 → 0.4.6

package/README.md

@@ -8,7 +8,9 @@ OrgX plugin for [OpenClaw](https://openclaw.ai) — connect your AI agents to Or
 2. Open `http://127.0.0.1:18789/orgx/live`.
 3. Click **Connect OrgX**.
 4. Sign in at [useorgx.com](https://useorgx.com) and approve the connection.
-5. Return to OpenClaw. The plugin stores a dedicated credential and runs first sync automatically.
+5. Return to OpenClaw. The plugin stores a dedicated credential and runs first sync automatically (no key copy/paste).
+
+If Claude/Cursor/Codex MCP configs are detected on this machine, the pairing flow also installs a local MCP bridge entry (no OAuth) pointing at `http://127.0.0.1:18789/orgx/mcp`. To avoid overwriting your hosted `orgx` server entry, the local bridge is installed under the name `orgx-openclaw`. To opt out entirely, set `ORGX_DISABLE_MCP_CLIENT_AUTOCONFIG=1`.
 
 Manual API key entry is still available as a permanent fallback from the onboarding panel.
 
@@ -18,6 +20,23 @@ Manual API key entry is still available as a permanent fallback from the onboard
 openclaw plugins install @useorgx/openclaw-plugin
 ```
 
+## Local MCP Bridge (Claude/Codex/Cursor)
+
+This plugin exposes the same `orgx_*` tools over a local MCP HTTP endpoint served by the OpenClaw gateway:
+
+- URL: `http://127.0.0.1:18789/orgx/mcp` (port follows your OpenClaw gateway config)
+- Why: avoids the separate cloud MCP OAuth flow and keeps the `oxk_...` key stored only in the plugin's credential store.
+
+On successful browser pairing, the plugin will attempt to patch:
+
+- `~/.claude/mcp.json` (adds `mcpServers["orgx-openclaw"]` pointing to the local bridge)
+- `~/.codex/config.toml` (add/update `[mcp_servers."orgx-openclaw"].url` to the local bridge)
+- `~/.cursor/mcp.json` (adds `mcpServers["orgx-openclaw"]` pointing to the local bridge)
+
+Each file is backed up first (only when a change is needed) with a `*.bak.<timestamp>-<rand>` suffix.
+
+Disable auto-config by setting `ORGX_DISABLE_MCP_CLIENT_AUTOCONFIG=1`.
+
 Or manually add to your OpenClaw config:
 
 ```json
@@ -42,10 +61,17 @@ Or manually add to your OpenClaw config:
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `apiKey` | string | — | Your OrgX API key (get one at [useorgx.com](https://useorgx.com)) |
+| `apiKey` | string | — | Your OrgX API key (optional if you use browser pairing from `/orgx/live`) |
 | `baseUrl` | string | `https://www.useorgx.com` | OrgX API base URL |
+| `syncIntervalMs` | number | `300000` | Background sync interval (ms) |
+| `enabled` | boolean | `true` | Enable/disable the plugin |
 | `dashboardEnabled` | boolean | `true` | Enable the live dashboard at `/orgx/live` |
 
+Environment overrides:
+
+- `ORGX_API_KEY` overrides `apiKey`
+- `ORGX_BASE_URL` overrides `baseUrl`
+
 ## Features
 
 ### 🛠️ MCP Tools
@@ -53,6 +79,8 @@ Or manually add to your OpenClaw config:
 The plugin registers these tools for your agents:
 
 - **`orgx_status`** — Get current org status (initiatives, agents, tasks, decisions)
+- **`orgx_status_json`** — Get current org status as JSON (for MCP Apps / automation)
+- **`orgx_live_app`** — Open the OrgX Live MCP App (interactive widget)
 - **`orgx_sync`** — Bidirectional memory sync with OrgX
 - **`orgx_spawn_check`** — Pre-spawn quality gate + model routing
 - **`orgx_quality_score`** — Record quality scores for completed work
@@ -72,6 +100,14 @@ Shows:
 - Activity stream
 - Outbox replay visibility for buffered offline events
 
+### 🔁 Auto-Continue (Scaffold → Agent Execution)
+
+If you scaffold an initiative from chat (for example, "plan X" and then create/scaffold), OrgX can automatically start executing the first workstream via the stream auto-continue pipeline.
+
+Troubleshooting:
+- If agents do not start automatically, say: `start agents` to re-trigger dispatch.
+- Open the live link (Mission Control) to see stream status (`ready`, `active`, `blocked`) and any upgrade/approval decisions.
+
 ### 🎯 Model Routing
 
 OrgX automatically routes tasks to the appropriate model tier:
@@ -96,6 +132,22 @@ Returns: { allowed: true, modelTier: "sonnet" }
 Agent spawns with recommended model
 ```
 
+### 🔑 BYOK (Bring Your Own Keys)
+
+If you use BYOK models (OpenAI, Anthropic, OpenRouter), store your provider keys in OpenClaw. The OrgX plugin reads OpenClaw settings and injects keys when it invokes OpenClaw CLI commands, so you do not need to put provider keys in the OrgX plugin config.
+
+### 🩺 Diagnostics
+
+- `openclaw orgx doctor` runs local checks and can optionally probe the OrgX API.
+- `openclaw gateway status --json` shows the OpenClaw gateway port and runtime state.
+
+### 🔁 Gateway Watchdog
+
+The plugin starts a lightweight watchdog daemon that periodically probes the local OpenClaw gateway and restarts it if needed.
+
+- Disable: `ORGX_DISABLE_GATEWAY_WATCHDOG=1`
+- Tune: `ORGX_GATEWAY_WATCHDOG_INTERVAL_MS`, `ORGX_GATEWAY_WATCHDOG_FAILURES`, `ORGX_GATEWAY_WATCHDOG_TIMEOUT_MS`
+
 ## Feature Matrix
 
 | Capability | Status | Notes |
@@ -163,6 +215,17 @@ Notes:
 Manual dispatch:
 - Use `docs/marketing/manual-agent-dispatch-golden-prompt.md` when manually launching a marketing agent for a specific task (non-batched dispatch).
 
+## SEO Automation (Keywords Everywhere + DataForSEO)
+
+This repo also includes a repo-local SEO pipeline runner (scripts only; not shipped in the plugin package) under `scripts/seo/`.
+
+- Apply an OrgX initiative plan for SEO automation: `npm run seo:plan`
+- Run the pipeline:
+  - Dry run (no API calls): `npm run seo:run -- --config=docs/seo/seo.config.example.json --mode=all --dry-run=true`
+  - Live run: `npm run seo:run -- --config=docs/seo/seo.config.example.json --mode=all`
+
+Details: `scripts/seo/README.md`
+
 ## API Endpoints
 
 When the plugin is loaded, these HTTP endpoints are available:
@@ -184,6 +247,7 @@ When the plugin is loaded, these HTTP endpoints are available:
 | `GET /orgx/api/live/activity` | Live activity feed |
 | `GET /orgx/api/live/stream` | Live SSE stream |
 | `GET /orgx/api/handoffs` | Handoff summaries |
+| `POST /orgx/mcp` | Local MCP bridge (tools/list, tools/call) |
 
 ## Requirements
 
@@ -191,6 +255,25 @@ When the plugin is loaded, these HTTP endpoints are available:
 - Node.js 18+
 - OrgX account (browser pairing recommended, API key fallback supported)
 
+## Maintainers: Release to NPM
+
+This repo publishes on GitHub Release via `.github/workflows/publish.yml`.
+
+1. Update versions
+   - `package.json` version (NPM version)
+   - `openclaw.plugin.json` version (what `openclaw plugins list` displays)
+   - `CHANGELOG.md`
+2. Verify
+   - `npm run typecheck`
+   - `npm run test:hooks`
+   - `npm run build`
+   - Optional: `npm run verify:clean-install`
+3. Publish
+   - Create a GitHub release for the tag (workflow publishes with provenance)
+4. Smoke test
+   - `openclaw plugins install @useorgx/openclaw-plugin@<version>`
+   - Verify `http://127.0.0.1:18789/orgx/live` pairing and `http://127.0.0.1:18789/orgx/mcp` MCP bridge
+
 ## Links
 
 - [OrgX](https://useorgx.com) — AI orchestration platform