@useorgx/wizard

One-line CLI onboarding that adds OrgX MCP configs, skills/rules, and companion plugins to your local AI tools.

Quick Start

pnpm install
pnpm build
node dist/cli.js --help

For local development, use pnpm dev -- --help.

What It Changes

The wizard modifies local tool configuration only. Depending on the command, it can:

• add OrgX MCP server entries to Claude, Cursor, Codex, VS Code, Windsurf, and Zed;
• install standalone OrgX skills/rules into Cursor and Claude Code;
• install companion OrgX plugins for Cursor, Claude Code, Codex, and OpenClaw so those tools receive OrgX skills, rules, MCP config, commands, hooks, and agent prompts through their plugin systems.

Commands

• setup adds OrgX MCP configs, standalone skills/rules, and companion plugins to detected AI tools. When OrgX auth is available in an interactive shell, it guides workspace selection or creation, can create the user's first live OrgX initiative, creates a starter onboarding task under that initiative, and prints a handoff prompt for the configured AI tool of choice. The founder preset preplans plugin installs before it writes standalone skills so plugin-backed hosts do not get duplicate standalone assets in the same run.
• surface list shows supported surfaces and current status.
• surface add <name> patches a specific surface.
• surface remove <name> removes OrgX-managed config from a specific surface.
• mcp add [surface] and mcp remove [surface] manage OrgX MCP entries in Claude, Cursor, Codex, VS Code, Windsurf, and Zed tool configs.
• plugins list shows companion plugin availability and install status for Cursor, Claude Code, Codex, and OpenClaw.
• plugins add [target...] installs the managed Cursor plugin bundle and managed OrgX companion plugins into Claude Code, Codex, and/or OpenClaw. Cursor, Claude Code, and Codex companion plugins carry their own OrgX skills/rules/MCP config and become the source of truth for those hosts.
• plugins remove [target...] uninstalls the managed Cursor plugin bundle, legacy managed Cursor rules, and managed OrgX companion plugins from Claude Code, Codex, and/or OpenClaw.
• uninstall removes OrgX-managed tool config, companion plugins, legacy managed Cursor rules, wizard-local auth, and wizard-local setup state. Use --keep-auth, --keep-state, --skip-plugins, or --skip-surfaces to preserve specific pieces.
• doctor verifies local config, hosted MCP reachability, npm registry readiness, current-workspace connectivity, local OpenClaw health, and optionally the remote setup status API. Hosted MCP tools are OAuth-scoped inside the client connector, so the wizard does not preflight them with oxk_ API keys. It exits non-zero when blocking connectivity issues remain.
• auth status shows the resolved OrgX API key source and verifies it against POST /api/client/sync.
• auth login [--base-url <url>] starts browser pairing against OrgX, waits for approval, saves the returned per-user key to the wizard auth store, and bootstraps OpenClaw auth if OpenClaw is detected. Use --api-key <oxk_...> for CI or blocked-browser fallback.
• auth set-key <oxk_...> [--base-url <url>] verifies a per-user OrgX key, saves it to the wizard auth store, and bootstraps OpenClaw auth if OpenClaw is detected.
• auth clear removes the wizard-local saved OrgX API key.
• workspace current, workspace list, workspace create <name>, and workspace set-default <id> inspect and manage OrgX workspaces.
• skills add [pack...] writes standalone OrgX skills/rules into supported local tools: .cursor/rules/orgx.md, .claude/skills/orgx/SKILL.md, and available OrgX Claude skill packs from useorgx/skills. If a companion plugin already owns a tool's OrgX skills/rules, the wizard skips those overlapping standalone assets and only installs the remaining standalone pieces.
• skills sync [pack...] recomposes generated skill/rule files from the OrgX-managed core plus any enabled local skill extensions.
• skills status shows local extension files and generated skill files tracked for drift protection.
• skills extensions add|edit|enable|disable|list manages user-editable skill extensions without changing the OrgX-managed core skill source.

CI Mode

• doctor is CI-friendly: it exits non-zero only when blocking issues remain, and keeps warnings such as an unpublished npm package non-fatal.
• auth set-key <oxk_...> can be driven with ORGX_BASE_URL in CI when the target OrgX API is not production.
• The intended verification baseline for changes is pnpm test, pnpm typecheck, and pnpm build.

Auth Notes

• The wizard uses per-user oxk_... keys for auth verification and local bootstrap. auth login now prefers secure browser pairing and falls back to direct key entry with --api-key.
• When keytar is available, the wizard stores the raw API key in the system keychain and keeps only metadata in auth.json. If keytar is unavailable or disabled, it falls back to file-backed storage in auth.json.
• doctor always checks https://mcp.useorgx.com/health and resolves the current workspace through the OrgX API. Hosted MCP tool calls are verified by the configured client connector after its OAuth flow completes, not by the wizard's per-user oxk_ key.
• doctor also checks npm registry reachability for @useorgx/wizard and reports whether the package is already published.
• Remote setup status is separate: doctor checks /api/setup/status only when ORGX_SERVICE_KEY is present because that endpoint is still service-key-only.
• Auth resolution order is ORGX_API_KEY, then the wizard auth store, then OpenClaw config.

Workspace Bootstrap

• wizard setup now opens a guided workspace picker in interactive shells, letting you keep the current default workspace, promote another existing workspace, or create a new one and make it active immediately.
• If the selected workspace has no remembered setup initiative, wizard setup offers to create a first initiative, defaulting to Make OrgX useful on this machine. It then creates the onboarding workstream and starter task inside that initiative so setup ends with a concrete next action instead of a blank workspace.
• Repeated setup runs are intentionally quiet. Daily Brief can be configured with defaults, customized, or skipped; skips for Daily Brief, first initiative creation, onboarding task creation, agent roster setup, and the first intent prompt are remembered per workspace so the wizard does not ask again on every run.
• After the first initiative is ready, setup prints the /live/<initiative> URL and a copyable prompt for the user's configured AI tool: continue the initiative, show the next action, and start with the onboarding task.
• wizard workspace current reads the current OrgX workspace from GET /api/v1/workspaces/current, with a fallback to workspace listing if that route is unavailable.
• wizard workspace list lists all accessible workspaces.
• wizard workspace create "Founders" --description "Initial OrgX workspace" creates a new workspace through POST /api/entities.
• wizard workspace set-default <id> updates the default workspace through the generic entity API.

Editor Rules, Skills, And Plugins

• wizard skills add writes the OrgX Cursor rule file at .cursor/rules/orgx.md.
• wizard plugins add cursor installs the full Cursor local plugin bundle at .cursor/plugins/local/cursor-plugin; it includes OrgX skills, rules, MCP config, commands, hooks, and agent prompts.
• wizard skills add also generates a hosted OrgX Claude skill at .claude/skills/orgx/SKILL.md.
• The same command installs available OrgX Claude skill packs by pulling their source files from useorgx/skills; pass specific pack names to limit what is installed.
• wizard skills add and wizard skills sync both compose generated outputs from OrgX-managed core skills plus any enabled extension files from the wizard skill-extension store.
• When the Cursor companion plugin is installed, that plugin owns Cursor-side OrgX skills, rules, MCP config, commands, hooks, and agent prompts. In that case wizard skills add remains the standalone rules fallback for Cursor installs that are not using the plugin.
• When the Claude Code companion plugin is installed, that plugin owns Claude-side OrgX skills and skill sync. In that case wizard skills add skips overlapping Claude assets instead of writing duplicate copies.
• The Codex companion plugin also bundles its own OrgX skills, so wizard skills add does not try to manage Codex skill files at all.
• Those generated rules expect artifact proof to use durable sources such as GitHub permalinks, public URLs, or absolute file paths / file://..., not OrgX wrapper routes like /live/..., /artifacts/..., or /console/....

Skill Extensions

OrgX core skills are treated as managed upstream content. User behavior lives in sidecar extension files so upgrades can refresh core skills without losing local preferences.

• wizard skills extensions add orgx --content "- Prefer short status updates." creates a user extension for the hosted OrgX base skill.
• wizard skills extensions edit morning-briefing creates the extension if needed and opens it in $EDITOR.
• wizard skills sync appends enabled extensions after the core skill content and writes the composed output into configured tools.
• Generated skill files are tracked in wizard state. If a generated file is edited by hand after sync, the next sync skips that file unless --force is passed. Move durable local behavior into skills extensions files instead of editing generated output directly.
• Extension scopes are user, workspace, and project. Today they are local sidecars; the same shape is intended to map to future OrgX account/workspace sync.

Release Flow

• GitHub Actions publishes to npm on pushes of version tags matching v*.
• The publish workflow installs dependencies with pnpm, runs pnpm typecheck, pnpm test, and pnpm build, then runs pnpm publish --no-git-checks.
• The workflow expects an NPM_TOKEN repository secret.

Troubleshooting

• If doctor reports hosted mcp unreachable, verify local network access to https://mcp.useorgx.com/health.
• If doctor reports orgx auth invalid, re-run wizard auth login to mint a fresh key or use wizard auth login --api-key <oxk_...> / wizard auth set-key <oxk_...> for manual fallback.
• If workspace resolution fails, re-run wizard workspace list after verifying the current OrgX base URL and API key.