feat: harden wizard flow and env mapping

README.md

@@ -160,27 +160,31 @@ const config = useSafeRuntimeConfig()
 
 [Shelve](https://shelve.cloud) is a secrets management service. This module fetches secrets from Shelve at build time and merges them into your runtime config before validation.
 
-### Zero-Config Setup
+### Configure Shelve
 
-If you have a `shelve.json` file in your project root, the integration enables automatically:
+Configure Shelve directly in your Nuxt config:
 
 ```ts
 export default defineNuxtConfig({
   safeRuntimeConfig: {
     $schema: runtimeConfigSchema,
-    shelve: true, // Auto-detects project, team, and environment
+    shelve: {
+      project: 'my-app',
+      slug: 'my-team',
+    },
   },
 })
 ```
 
 The module resolves configuration from multiple sources (highest priority first):
 
-| Config      | Sources                                                                |
-| ----------- | ---------------------------------------------------------------------- |
-| project     | `nuxt.config` → `SHELVE_PROJECT` → `shelve.json` → `package.json` name |
-| slug        | `nuxt.config` → `SHELVE_TEAM_SLUG` → `shelve.json`                     |
-| environment | `nuxt.config` → `SHELVE_ENV` → `shelve.json` → dev mode auto           |
-| token       | `SHELVE_TOKEN` → `~/.shelve` file                                      |
+| Config      | Sources                                                      |
+| ----------- | ------------------------------------------------------------ |
+| project     | `nuxt.config` → `SHELVE_PROJECT` → `package.json` name       |
+| slug        | `nuxt.config.slug/team` → `SHELVE_TEAM` → `SHELVE_TEAM_SLUG` |
+| environment | `nuxt.config` → `SHELVE_ENV` → dev mode auto                 |
+| url         | `nuxt.config` → `SHELVE_URL` → `https://app.shelve.cloud`    |
+| token       | `SHELVE_TOKEN` → `~/.shelve`                                 |
 
 ### Explicit Configuration
 
@@ -232,6 +236,14 @@ export default defineNuxtConfig({
 
 The runtime plugin runs before validation, so freshly fetched secrets are validated against your schema.
 
+### Install Wizard UX
+
+On module install, an interactive setup wizard can help bootstrap validation and Shelve config. The wizard now:
+
+- shows a preview of planned actions first (install deps, write `~/.shelve`, edit `nuxt.config`)
+- asks for a final confirmation before applying any change
+- skips automatically in CI and non-interactive terminals (non-TTY)
+
 ## Runtime Validation
 
 By default, validation only runs at build time. Enable runtime validation to catch environment variable issues when the server starts:
@@ -311,6 +323,12 @@ When validation fails, you see detailed error messages:
 
 The module stops the build process until all validation errors are resolved.
 
+## Upcoming Major Release Notes
+
+- Shelve setup no longer documents `shelve.json` auto-enablement; supported sources are `nuxt.config`, env vars, and `package.json` fallback for project name.
+- The install wizard now previews actions and requires explicit confirmation before mutating files or writing credentials.
+- Runtime and wizard key-shaping now use the same env-key mapping rules to avoid schema/runtime drift.
+
 ## Why This Module?
 
 Nuxt's built-in schema validation is designed for module authors and broader configuration. This module focuses specifically on **runtime config validation** using Standard Schema, allowing you to:

docs/3.integrations/2.shelve.md

@@ -57,6 +57,18 @@ export default defineNuxtConfig({
 
 For local development, run `shelve login` to authenticate. For CI/CD, set the `SHELVE_TOKEN` environment variable.
 
+## Setup Wizard
+
+On module install (interactive terminals only), the setup wizard can bootstrap schema + Shelve configuration.
+
+Before mutating anything, it shows the planned actions and asks for final confirmation:
+
+- install validation dependencies (if needed)
+- write `~/.shelve` token (if newly entered)
+- update `nuxt.config`
+
+In CI and non-interactive terminals, the wizard is skipped automatically.
+
 ## How It Works
 
 1. The module reads your Shelve configuration from nuxt.config
@@ -170,7 +182,17 @@ You can override any configuration using environment variables:
 | ------------------ | ------------------------------ |
 | `SHELVE_TOKEN`     | Authentication token           |
 | `SHELVE_PROJECT`   | Project name                   |
+| `SHELVE_TEAM`      | Team slug                      |
 | `SHELVE_TEAM_SLUG` | Team slug                      |
 | `SHELVE_ENV`       | Environment name               |
 | `SHELVE_URL`       | API URL (for self-hosted)      |
 
+Resolution priority (high to low):
+
+| Config        | Priority                                                           |
+| ------------- | ------------------------------------------------------------------ |
+| `project`     | `nuxt.config` → `SHELVE_PROJECT` → `package.json` name             |
+| `slug`        | `nuxt.config.slug/team` → `SHELVE_TEAM` → `SHELVE_TEAM_SLUG`       |
+| `environment` | `nuxt.config` → `SHELVE_ENV` → auto (`development`/`production`)   |
+| `url`         | `nuxt.config` → `SHELVE_URL` → `https://app.shelve.cloud`          |
+| `token`       | `SHELVE_TOKEN` → `~/.shelve`                                       |