@userreason/wizard 0.1.0 → 0.2.1

package/README.md

@@ -1,51 +1,139 @@
-# @userreason/wizard
+# UserReason installation wizard
 
-Authenticated installation for UserReason. It shares the CLI client and credentials, uses the same onboarding endpoints, and generates integrations for React, Next.js, Vue and plain browser applications. This package is prepared for publication; no npm publication occurs during its build.
+Add UserReason feedback to your application with a guided setup for **React,
+Next.js, Vue and browser JavaScript**. The wizard installs the SDK and project
+CLI, connects your workspace and previews the integration before applying it.
 
-Build the local CLI first, then the wizard:
+[Quickstart](https://docs.userreason.com/get-started/quickstart/) ·
+[SDK documentation](https://docs.userreason.com/sdk/initialization/) ·
+[Dashboard](https://dash.userreason.com)
+
+## Requirements
+
+- Node.js **22.12 or later** and npm, pnpm or Yarn.
+- Your application's source directory and permission to install dependencies.
+- A browser to sign in to UserReason and approve the installation.
+
+## Install
+
+Run this command from your application directory:
 
 ```sh
-cd ../ur-cli && npm ci && npm run build
-cd ../ur-wizard && npm ci && npm run typecheck && npm test
-node dist/bin.js --help
+npx -y @userreason/wizard@latest
 ```
 
-The wizard bundles the CLI client at build time. Its published runtime does not depend on the private `ur-types` package or a local file reference; its only runtime dependency is the OS credential-store binding.
+The wizard will:
 
-After publication:
+1. Detect your framework, package manager and any existing UserReason setup.
+2. Open the browser so you can sign in and approve installation access.
+3. Let you choose or create a workspace and site.
+4. Show the proposed application change and optional setup steps for review.
+5. Install `@userreason/js` and the project-local `@userreason/cli`, apply the
+   approved integration and check that the site's configuration is available.
+
+Start your application afterward and follow the next steps shown in the
+terminal. The [first survey guide](https://docs.userreason.com/get-started/first-prompt/)
+walks through creating and publishing a survey. Installing the SDK does not
+publish a survey.
+
+For a different application directory:
 
 ```sh
-npx -y @userreason/wizard@latest
+npx -y @userreason/wizard@latest --directory ./my-app
+```
+
+## What changes in your application
+
+The SDK is added to `dependencies`, and the CLI to `devDependencies`. For a
+supported entry point, the integration initializes UserReason with your public
+site ID:
+
+```js
+import UserReason from '@userreason/js';
+
+UserReason.init({ siteId: 'YOUR_SITE_ID' });
+```
+
+React, Vue and browser applications initialize before the app mounts. Modern
+Next.js applications use client instrumentation; older supported versions use a
+small client component. If your entry point needs a custom integration, the
+wizard provides manual instructions.
+
+Existing initialization is detected on reruns. The wizard previews source edits
+and preserves existing integrations and customized agent guidance. Only public
+SDK configuration belongs in application source; sign-in credentials are stored
+separately.
+
+## Optional setup
+
+The setup review can also include:
+
+- **Project agent guidance:** a short note in an existing `AGENTS.md` or
+  `CLAUDE.md`, plus a UserReason feedback skill for compatible agents.
+- **Ongoing CLI access:** a separate account connection for reading feedback and
+  managing surveys, subject to the permissions you approve.
+- **Global CLI:** make `userreason` available outside this project through npm's
+  configured global installation location.
+
+The project-local CLI works without a global installation:
+
+```sh
+npx --no-install userreason whoami
+npx --no-install userreason prompt list
+npx --no-install userreason docs search "survey targeting"
 ```
 
-It discovers the public WorkOS client ID from the configured API, reads the selected project's `package.json`, detects its framework/package manager, reuses an existing OS-stored login or starts public WorkOS device authentication, and selects or creates a workspace and site. `--client-id` remains available for explicit configuration. Only when the operation lacks an effective grant does it ask the human to approve installation permissions. A previously approved client can continue unattended until its grant expires or is revoked. Fresh clients may choose an existing workspace in the browser approval screen even before they have permission to list its name.
+Use `pnpm exec userreason` or `yarn exec userreason` in those projects. Teammates
+install the project's dependencies and connect their own account with
+`userreason login --open`; they do not need to create another site.
+
+## Update an existing installation
 
 ```sh
-npx -y @userreason/wizard@latest \
-  --directory ./app \
-  --workspace WORKSPACE_UUID \
-  --site SITE_UUID \
-  --origin https://app.example.com \
-  --install \
-  --yes \
-  --json
+npx -y @userreason/wizard@latest --refresh
 ```
 
-For new resources, use `--workspace-name` and `--site-name` instead of their UUID flags. `--dev` selects the development API, development WorkOS client configuration and default site environment. `--environment` can select the site's environment independently of the API deployment. Production sites require HTTPS origins.
+Refresh updates the SDK and project CLI without repeating onboarding or
+rewriting the application's initialization. Restart or reload your application
+to use the updated SDK. Use `--install` to force package installation.
+
+## Preview and scripted setup
 
-`--install` installs `@userreason/js@^0.2.0` with the detected package manager and dependency scripts disabled. This requires that the remote-compatible SDK has been published first. `--skip-install` prepares the integration without changing dependencies; ensure your existing SDK supports `init({workspaceId, siteId, apiBaseUrl})`. SDK 0.1.x's local-survey API cannot connect to the Worker's remote campaign protocol.
+Inspect a plan without signing in, installing packages or changing files:
 
-Generated files:
+```sh
+npx -y @userreason/wizard@latest --dry-run
+```
+
+For a scripted installation with an existing workspace and site:
+
+```sh
+npx -y @userreason/wizard@latest \
+  --workspace WORKSPACE_UUID \
+  --site SITE_UUID \
+  --yes --integrate --json
+```
 
-- `userreason.config.json`: public workspace/site/API configuration and required SDK version.
-- `src/userreason.generated.tsx` for React/Next.js, or `src/userreason.generated.ts` for Vue/vanilla; written at the project root when there is no `src` directory.
+Browser approval is still required. `--yes` accepts the main installation plan;
+optional global installation, ongoing CLI access and agent guidance require
+explicit flags in scripted use. Run `--help` for all options. `--no-open` prints
+the sign-in link for use in another browser.
 
-The generated React/Next component, Vue composable or vanilla initializer must be mounted/called once at the application root. The wizard prints the framework-specific instruction and includes lifecycle cleanup. It leaves existing application source unchanged so the integration can be reviewed. Files are reused if identical; changed files require `--force`, which creates a backup before replacement. Symlinked source directories are refused.
+## Environments and access
 
-React/Next initialization uses a browser layout effect with an SSR-safe fallback, so ordinary descendant `useEffect` calls can report their first event after initialization. Cleanup and reinitialization also run correctly during React Strict Mode's development remount. Descendant layout effects can run earlier: move their event reports to a passive effect or initialize UserReason through a controlled browser entry before rendering that tree. Vue initializes in the root `onBeforeMount`, ahead of descendant mount hooks; call the composable in the root setup before creating descendants. Neither framework starts the SDK during server rendering. Remote configuration still loads asynchronously: await `UserReason.ready()` when an event must wait for its targeting configuration. See [React layout effects](https://react.dev/reference/react/useLayoutEffect) and [Vue lifecycle hooks](https://vuejs.org/api/composition-api-lifecycle.html#onbeforemount).
+The wizard uses the production UserReason API by default. For a customer site
+used in local development or previews, choose `--environment development`.
+This setting describes your site; it does not select a different UserReason API.
 
-The wizard checks the public SDK configuration endpoint using the exact allowed host origin. Its result explicitly reports `hostConnectionVerified:false`: configuration availability is not proof of a real browser connection. Start the host application, mount the generated integration, and verify its config/session flow from that origin. No campaign is published merely by installing the SDK.
+New sites allow any origin by default. Add `--origin https://app.example.com` to
+restrict a new site to an exact origin, or manage restrictions in the dashboard.
+Existing site restrictions are preserved.
 
-Only public SDK configuration is written into the project. Login tokens remain in macOS Keychain, Windows Credential Manager or Linux Secret Service. WorkOS API keys and UserReason signing keys are never required by the wizard.
+Installation access is short-lived and cannot publish surveys. Ongoing CLI
+access is a separate approval that you can review or revoke in the dashboard.
+Per-user credentials use file storage by default; `--credential-store keychain`
+selects the available OS credential store. Your application source is parsed
+locally and is not uploaded to an AI service.
 
-Local tests use temporary projects and HTTP fixtures. Live login, grant approval, npm installation and host-origin operation require the configured WorkOS environment, migrations and deployed onboarding Worker.
+See [troubleshooting](https://docs.userreason.com/get-started/troubleshooting/)
+for help with installation, sign-in, permissions and browser verification.