@useorgx/wizard 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# @useorgx/wizard
+
+One-line CLI onboarding for OrgX surfaces.
+
+## Quick Start
+
+```bash
+pnpm install
+pnpm build
+node dist/cli.js --help
+```
+
+For local development, use `pnpm dev -- --help`.
+
+## Commands
+
+- `setup` configures detected automated surfaces and, when OrgX auth is available in an interactive shell, guides workspace selection or creation.
+- `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 Claude, Cursor, Codex, VS Code, Windsurf, and Zed MCP entries.
+- `doctor` verifies local config, hosted MCP reachability, an authenticated hosted MCP `get_setup_status` tool call when OrgX user auth is configured, npm registry readiness, current-workspace connectivity, local OpenClaw health, and optionally the remote setup status API. 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 `.cursor/rules/orgx.md`, generates `.claude/skills/orgx/SKILL.md`, and installs the default OrgX Claude skill packs (`morning-briefing`, `initiative-kickoff`, `bulk-create`, `nightly-recap`) from `useorgx/skills`.
+
+## 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, when user auth is configured, initializes an authenticated MCP session against `https://mcp.useorgx.com/mcp` and calls `get_setup_status` before resolving the current workspace through the OrgX API.
+- `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.
+- `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 And Skills
+
+- `wizard skills add` writes the OrgX Cursor rule file at `.cursor/rules/orgx.md`.
+- `wizard skills add` also generates a hosted OrgX Claude skill at `.claude/skills/orgx/SKILL.md`.
+- The same command installs the four starter OrgX Claude skill packs by pulling their source files from `useorgx/skills`.
+
+## 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 --provenance`.
+- 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.