# @useorgx/wizard One-line CLI onboarding and AQ profiling for local AI work. The wizard can add OrgX MCP configs, skills/rules, and companion plugins, then scan real AI-session receipts to show your current Agentic Quotient, reachable ceiling, and first repair that raises execution capacity. ## Quick Start ```bash 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; - detect the audited DeepSeek Harness release, install the OrgX DSH plugin, and launch its headless profile with refreshed browser OAuth; - install standalone OrgX skills/rules into Cursor and Claude Code; - install companion OrgX plugins for Cursor, Claude Code, Codex, OpenCode, and OpenClaw. The Claude Code plugin is a policy-safe static bundle: user-invoked skills and commands plus a focused, non-destructive, closed-world OrgX status profile through native OAuth, with no runtime hooks or transcript/context sync code. ## 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. - `deepseek ` refreshes the wizard's OrgX OAuth token, strips any separate `ORGX_API_KEY` gateway authority, and runs the pinned DSH `headless` profile with the OrgX MCP access token. It fails closed when DSH, OAuth refresh, or the audited runtime version is unavailable. - `work-graph profile --from all --publish --public-share` runs AQ from recent AI-work receipts, publishes a redacted profile, and prints a four-signal operating profile plus the first AQ-lifting repair to execute next. - Every profile or preview writes both the full evidence report and a compact, machine-safe `work-graph-agent-brief-*.md` with provenance, the growth edge, and a ready prompt for the smallest verifiable repair. - `work-graph preview --from all` shows the same profile story locally without publishing. - `work-graph runtime-event --source codex|claude --summary "..."` lets an agent write public-safe runtime evidence that the next AQ profile can collect. - `hooks install [--targets codex,claude-code]` installs bounded local capture hooks. Terminal session events and adapter-supplied `RunEnd` events write compact summaries to a durable queue, then request a detached single-flight delivery worker. `RunEnd` represents one completed agent run inside a conversation that may continue. Receipt-ready captures remain queued until the server confirms that the automatic receipt was persisted; a session-only 2xx response is not enough. The hook does not read credentials or perform network I/O. Set `ORGX_SESSION_SUMMARY_AUTO_FLUSH=off` for local-only capture and manual delivery. The legacy transcript-derived execution-graph emit remains off unless `ORGX_EMIT_EXECUTION_GRAPH=1` is set. - `sessions context set --file --cwd "$PWD" --source-client --session-id --context-sha256 ` validates one producer-asserted `orgx-session-work-context/v1` record and binds it to that exact native session. The JSON acknowledgement names the v2 activation contract and accepted SHA-256 fingerprint; a different session in the same directory cannot consume it. `sessions context show` and `sessions context clear` accept the same client/session pair. The cwd-only form is a one-session launch lease: the first supported native `SessionStart` in that exact directory atomically claims it, rewrites it as a client-and-session-bound v2 activation, and leaves concurrent sessions without context. Use an explicit client/session pair when more than one session may start. Expired, invalid, mismatched, or tampered records are ignored. `ORGX_SESSION_WORK_CONTEXT` remains the process-scoped override for launchers that already provide it. The Wizard does not infer intent, authority, cost, or semantic references from prompts. - `hooks flush [--limit 100]` is the manual delivery and recovery path. It uses the same queue lease as automatic delivery and removes each valid file only after a successful server acknowledgement. Failed captures stay queued for retry; malformed captures move to the owner-only `session-summary-captures/quarantine/` directory and make a manual flush fail visibly without being deleted. - `hooks doctor` shows generated-hook status (`current`, `stale`, or `missing`), automatic-delivery configuration, active and quarantined capture counts, the legacy spool count, current-directory work-context readiness, and separate capture, first-turn context, and receipt readiness for Claude Code, Codex, Cursor, and OpenCode without changing local configuration. Add `--json` for the versioned `orgx-client-continuity/v2` machine contract, per-client terminal boundary, warnings, and exact next action. - `hooks backfill` previews compact summaries distilled from the legacy spool. It does not upload or archive anything unless you add `--post --yes`; `--truncate` also requires both flags and archives the original spool only after every upload succeeds. - `map [query...] --deep-search` runs the v1 Operating Map discovery flow over connected company signals and cited deep research, prints source health and low-confidence ProcessCards, and keeps ownership/timing/"done" confirmation human-gated. Add `--candidate --yes` to explicitly propose one card as an OperatingProcess; the wizard never auto-confirms or activates inferred workflow ownership. - `surface list` shows supported surfaces and current status. - `surface add ` patches a specific surface. - `surface remove ` 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, OpenCode, and OpenClaw. - `plugins add [target...]` installs the managed Cursor plugin bundle and managed OrgX companion plugins into Claude Code, Codex, OpenCode, and/or OpenClaw. For OpenCode, it adds `@useorgx/orgx-opencode-plugin@alpha` to the global plugin array and leaves credentials in their existing environment or credential store. - `plugins remove [target...]` uninstalls Wizard-managed OrgX companion plugins from Cursor, Claude Code, Codex, OpenCode, and/or OpenClaw. OpenCode local paths and pinned package versions are user-managed and remain in place. - `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. - `doctor --workload [--json]` is a separate, account-free path that reads a credential-free workload-shape JSON document from a file or stdin (`-`) and makes exactly one unauthenticated request to the public Workload Doctor. It does not load an API key, run health checks, emit telemetry, or create wizard state. Input is rejected before upload when it is invalid, credential-shaped, or larger than 16 KiB. Production uses `https://useorgx.com`; `--base-url ` is an explicit testing/self-hosted override and requires HTTPS except for loopback hosts. - `auth status` shows the resolved OrgX API key source and verifies it against `POST /api/client/sync`. - `auth login [--base-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 ` for CI or blocked-browser fallback. - `auth set-key [--base-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 `, and `workspace set-default ` 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 ` 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`. ## Anonymous Telemetry The wizard sends anonymous setup and verification outcomes to OrgX so release health can be measured across supported CLI and plugin surfaces. Events use a random installation identifier and coarse outcome metadata; they do not include API keys, prompts, command output, file contents, or workspace paths. The account-free `doctor --workload` path is excluded from wizard telemetry and does not create or read the wizard installation identifier. Set `ORGX_TELEMETRY_DISABLED=1` or `ORGX_TELEMETRY_ENABLED=0` to opt out. ## 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 --workload` does not run those authenticated checks; it only submits the bounded workload shape to `https://useorgx.com/api/v1/doctor/workload` (or the explicit safe `--base-url` override). - `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. - DeepSeek setup pins `@deepseek-ai/dsh@0.1.0-rc.6` and `@useorgx/deepseek-harness-plugin@0.1.0`. The launcher uses the wizard's browser OAuth access and refresh tokens for hosted MCP; it does not reuse an `oxk_` gateway key as an MCP token. ## 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/` 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. - The AQ loop is: run profile, claim the public Work Graph, start the selected repair quest in OrgX, attach proof, rerun the profile, and compare the AQ delta. - The Operating Map loop is: `wizard map --deep-search "Map the intake, handoffs, systems of record, and completion criteria"`, inspect citations/source health/limitations, propose only a reviewed ProcessCard, confirm it in OrgX, then use the resulting OperatingProcess as the source for adoption and ValueCase projections. A cited report without a schema-valid candidate block remains observation-only. - `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 ` 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, it owns Claude-side static OrgX skills, user-invoked commands, and the pinned `https://mcp.useorgx.com/mcp?profile=claude-directory` native-OAuth MCP connection. The bundle has no hooks or dynamic transcript/context sync code, and `wizard skills add` skips overlapping Claude assets instead of writing duplicate copies. - Claude plugin installs are fetched from the reviewed release tag rather than a mutable branch. Before a staged local replacement, the wizard validates the exact static file set, reviewed plugin manifest, MCP object, exact endpoint, and prohibited runtime content. A symlinked destination root or symlink occupying an expected managed path is rejected; unexpected legacy links are pruned by an atomic directory replacement without following them. Existing Claude installations are then refreshed with `claude plugin update` so the installed cache advances too. - The Codex companion plugin also bundles its own OrgX skills, so `wizard skills add` does not try to manage Codex skill files at all. - The OpenCode companion entry uses OpenCode's native npm plugin loader. The Wizard preserves JSONC comments and unrelated config, rejects ambiguous `opencode.json`/`opencode.jsonc` state, and never writes `ORGX_API_KEY` or `ORGX_WORKSPACE_ID` into either file. - 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 uses Node 22, pnpm 10.7.1, and npm 11.16.0; it runs `pnpm typecheck`, `pnpm test`, and `pnpm build`, verifies the tag matches the package version, then runs `npm publish --access public`. - npm authentication uses GitHub Actions trusted publishing through OIDC, so the release does not require a long-lived `NPM_TOKEN`. ## 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 ` / `wizard auth set-key ` for manual fallback. - If workspace resolution fails, re-run `wizard workspace list` after verifying the current OrgX base URL and API key.