@userreason/wizard 0.1.0 → 0.2.0

package/dist/skills/userreason/references/management.md

@@ -0,0 +1,61 @@
+# Authenticated management
+
+Use `npx --no-install userreason` from the application directory to run the CLI installed by the wizard; `--help` lists every command and `--json` gives machine-readable results on stdout (login and approval instructions go to stderr). The commands below abbreviate this to `userreason`. An authenticated UserReason MCP connection offers the same operations: inspect its tools rather than inventing names. Find commands offline with `userreason cli search "<task>"`, then read exact usage with `userreason cli get "<command>"`. The bundled command reference is `userreason docs get /cli/`; it needs no login or network. Read it for exact arguments; this page covers what to be careful about.
+
+## Access
+
+Run `whoami --json` to check the account, API and detected project target. The CLI reads the app's literal SDK `siteId` and `apiBaseUrl`, resolves that site's workspace and uses it automatically. Never choose a different accessible site to work around missing access. If initialization is dynamic or ambiguous, supply explicit `--workspace UUID --site UUID` and the matching `--dev` or `--api-url`. Explicit workspace selection does not inherit a project's site.
+
+`login --open` connects the CLI and opens consent. By default it requests all current and future workspaces and available permissions; the human can narrow either on the approval page. Current workspace roles still limit every action. Existing grants are never silently expanded. If access is missing, expired or excludes this project, run `access --open` and let the human review it, then retry the intended command. Use `grant request … --scope SCOPE --wait` only when a deliberately restricted connection is wanted. Stop on denied or revoked access; never substitute another identity.
+
+Credentials stay outside the project in a user-only file by default, or the OS credential store when selected with `login --credential-store keychain`; no API key or signing secret belongs in the project. A wizard installation grant cannot publish. Ongoing CLI authorization is a separate optional step offered by the wizard. Once that connection covers the requested operation, use it without requesting another grant for each task.
+
+| To do | Scope |
+| --- | --- |
+| Read surveys, audiences, events, results, responses, users and eligibility | `site:read` |
+| Read workspace members | `workspace:read` |
+| Save survey and audience drafts, register events | `survey:write` |
+| Publish, pause, resume or archive a survey; publish an audience | `campaign:publish` |
+| Change site settings, including the frequency policy (owners and admins) | `site:update` |
+| Permanently delete a workspace, site or survey (owners and admins) | `resource:delete` |
+
+Responses, users and eligibility hold personal data. Read what the task needs, quote sparingly, and do not copy it into the repository, commit messages or logs.
+
+A `read_failed`, `write_failed`, `lock_failed`, `native_addons_blocked` or `network_blocked` error is a local execution restriction, not missing account access. Request the local read/write/network capability the error names; do not request a broader UserReason grant. Valid sessions need no lock or credential write; refreshing an expired token does. Existing Keychain logins can be reused with `--credential-store keychain`. `docs search --offline` searches only the bundled CLI catalog; SDK details require the hosted docs. A fallback search result is labelled `source: "bundled"`.
+
+## Reading
+
+For survey methodology, read `/prompts/survey-quality/`, `/prompts/answer-order/` and `/prompts/experiments/` through the selected docs site. The docs are the shared guidance; keep runtime explanations focused on this draft's diagnostics and publication effects. Development builds support `results experiments PROMPT_UUID` (`--run`, `--all-attempts`, `--reported-only`) and `responses list --run UUID --variant ID`. Read the docs for definitions before interpreting these counts.
+
+- Surveys and audiences: `prompt list|get`, `audience list|get`. `get` returns the draft, what is published, and the `revision` every change needs.
+- Results: `results overview`, `results prompt PROMPT_UUID`, `results breakdown --by country`. Responses in words: `responses list`.
+- People: `user list`, `user get USER_UUID`, and `user eligibility USER_UUID` for why this person does or does not get each published survey, check by check. Add `--file AUDIENCE.json` to try an unpublished audience on them; nothing is saved.
+- Is the SDK connected: `site activity`. Events received: `event overview`.
+- Draft readiness: `prompt validate --file PROMPT.json`, optionally with `--context-file EXAMPLE.json` containing `application_context` and `local_events`. This saves nothing and reports missing facts, collection policies and required client capabilities. It does not establish real visitor history or prove a survey appears.
+
+Interpret choice answers through the content pinned to the response, never through the current draft. A response rate needs the shown count from the same period; do not invent a denominator.
+
+## Changing
+
+Saving a draft and publishing it are separate actions with separate permissions. Drafts reach nobody.
+
+- **Read first, then change.** Take the current `revision` from `get`. On a revision conflict, reread and reconcile; do not retry blindly with the newer number.
+- **Files are complete, not patches.** `prompt create|update` and `audience create|update` take the whole definition. Keep question, option and ending IDs stable when editing copy.
+- **Retries.** On a timeout, repeat the same command with the request and resource IDs printed in the error. Change nothing else.
+- **Publishing a survey** can reach real visitors. Do it only for the survey the human approved.
+- **Publishing a saved audience** changes every live survey that follows it, at once, without republishing them. Name the surveys in `used_by` and get approval first.
+- **The site's frequency policy** (`site frequency set`) applies to every live survey at once. Read it with `site frequency get` and change it only when asked.
+- **A new enrollment** (a changed `enrollment_epoch`) redraws the sample and restarts each person's counts. Keep it unchanged on ordinary edits.
+- **Event policies.** Choose from expected volume and the need for retained history. Use the business preset for ordinary-volume events whose server history the authorized task needs, and the activity preset for frequent local signals. These are configurable policies, not classifications inferred from event names. Explain collection and retention; do not silently expand high-volume uploads. `site events preview --mode explicit` previews migration and returns the revision and any required confirmation token; `site events set` applies that reviewed change. Existing grants may already cover these actions.
+- **Permanent deletion** removes the selected resource and its associated data. Only use it when the human explicitly requests permanent deletion; archive/disable keeps data. Run `workspace delete UUID --preview`, `site delete UUID --preview`, or `prompt delete UUID --preview`, review counts and references, then pass the exact `--confirm NAME`, `--revision N` and `--confirmation-token TOKEN`. Preserve `--request-id` on retries. `deletion status --workspace UUID --id JOB_UUID` follows cleanup after the resource disappears. Resolve references before deleting a survey. Existing grants need `resource:delete`; request updated access only if it is missing.
+- Archive and disable operations retain published versions and responses. Legacy generic `site.delete` and `survey.delete` commands still mean disable/archive; use the dedicated deletion flow for permanent removal.
+
+After publishing, verify a real browser opportunity before calling it working: the configuration being available is not proof that a survey appears. `user eligibility` and `/get-started/troubleshooting/` explain a survey that does not show.
+
+Use successful results' `links` in the completion message: `edit` after creating or updating a survey draft; `results` after publishing, pausing or resuming; `responses` when discussing answers; and `dashboard` for audiences, events and settings. New sites also return `install`. State the action's actual outcome: updating a live survey saves a draft and leaves its published version unchanged. After several changes to the same resource, share its final relevant link once. A local proposal or validation alone has no saved survey to link to. If no link is returned, omit it rather than guess. For setup or troubleshooting, use a relevant docs search result's `url` (the human-readable section), not its `markdown_url`.
+
+## Onboarding
+
+For SDK installation, run `npx -y @userreason/wizard@latest` in the project and review the edit it proposes. Only the public site ID and API configuration belong in host code. List existing workspaces and sites before creating new ones.
+
+A new ongoing consent replaces earlier grants for that client and login, so narrowing permissions takes effect immediately. Other signed-in devices keep their own connections.

package/dist/startup.js

@@ -0,0 +1,11 @@
+import { createRequire as createWizardRequire } from 'node:module'; import { fileURLToPath as wizardFileURLToPath } from 'node:url'; import { dirname as wizardDirname } from 'node:path'; const require = createWizardRequire(import.meta.url); const __filename = wizardFileURLToPath(import.meta.url); const __dirname = wizardDirname(__filename);
+import {
+  ensureCurrentWizard,
+  wizardVersion
+} from "./chunk-6CJ4ANMN.js";
+import "./chunk-GGARVSPT.js";
+import "./chunk-WL3NOIM6.js";
+export {
+  ensureCurrentWizard,
+  wizardVersion
+};

package/dist/state.js

@@ -0,0 +1,18 @@
+import { createRequire as createWizardRequire } from 'node:module'; import { fileURLToPath as wizardFileURLToPath } from 'node:url'; import { dirname as wizardDirname } from 'node:path'; const require = createWizardRequire(import.meta.url); const __filename = wizardFileURLToPath(import.meta.url); const __dirname = wizardDirname(__filename);
+import {
+  clearInstallation,
+  resolveInstallation,
+  saveInstallation,
+  savedInstallation
+} from "./chunk-FC7PZNYW.js";
+import "./chunk-6DCCEVPD.js";
+import "./chunk-YMSGDC4B.js";
+import "./chunk-OEGNGGZ2.js";
+import "./chunk-GGARVSPT.js";
+import "./chunk-WL3NOIM6.js";
+export {
+  clearInstallation,
+  resolveInstallation,
+  saveInstallation,
+  savedInstallation
+};

package/dist/ui.js

@@ -0,0 +1,23 @@
+import { createRequire as createWizardRequire } from 'node:module'; import { fileURLToPath as wizardFileURLToPath } from 'node:url'; import { dirname as wizardDirname } from 'node:path'; const require = createWizardRequire(import.meta.url); const __filename = wizardFileURLToPath(import.meta.url); const __dirname = wizardDirname(__filename);
+import {
+  Cancelled,
+  Terminal,
+  approvalProgressMessage,
+  approvalStatus,
+  clean,
+  cleanStyled,
+  normalizeOrigin,
+  openBrowser
+} from "./chunk-SJVLAYGG.js";
+import "./chunk-GGARVSPT.js";
+import "./chunk-WL3NOIM6.js";
+export {
+  Cancelled,
+  Terminal,
+  approvalProgressMessage,
+  approvalStatus,
+  clean,
+  cleanStyled,
+  normalizeOrigin,
+  openBrowser
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@userreason/wizard",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Authenticated UserReason SDK installation wizard",
   "type": "module",
   "license": "UNLICENSED",
@@ -14,23 +14,13 @@
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "typecheck": "tsc --noEmit",
-    "test": "npm run build && node --test tests/*.test.mjs",
-    "prepack": "npm run build"
-  },
-  "dependencies": {
+  "dependencies": {},
+  "optionalDependencies": {
     "@napi-rs/keyring": "2.1.0"
   },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "@userreason/cli": "file:../ur-cli",
-    "esbuild": "^0.28.0",
-    "react": "19.2.4",
-    "react-dom": "19.2.4",
-    "react-test-renderer": "19.2.4",
-    "typescript": "^5.9.0",
-    "vue": "3.5.43"
+  "homepage": "https://docs.userreason.com/get-started/quickstart/",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   }
 }