vaulter 1.0.66 → 1.0.73

package/README.md

@@ -26,14 +26,81 @@ curl -fsSL https://raw.githubusercontent.com/forattini-dev/vaulter/main/install.
 
 ## Quick Start
 
+### Minimal
+
 ```bash
 vaulter init                                          # Initialize project
 vaulter key generate --name master                    # Generate encryption key
-vaulter var set DATABASE_URL="postgres://..." -e dev  # Set secret
-vaulter var set PORT::3000 -e dev                     # Set config (plain)
+vaulter change set DATABASE_URL="postgres://..." -e dev  # Set secret
+vaulter change set PORT::3000 -e dev                     # Set config (plain)
+vaulter change set NODE_ENV=local -e dev                 # Set config (sensitive=false)
+vaulter change move API_KEY --from shared --to api -e dev # Move variable to service
+vaulter change move API_KEY --from shared -e dev -s svc-notifications   # Infer destination service
+vaulter plan -e dev                                      # Preview changes before applying
 eval $(vaulter export shell -e dev)                   # Export to shell
 ```
 
+### End-to-End (Monorepo, `web` + `api`)
+
+This flow shows local editing, team sharing, and promotion across multiple environments.
+
+```bash
+# 0) Initialize + discover services
+vaulter init --monorepo
+vaulter key generate --name master
+vaulter services
+
+# 1) Create/override vars locally (offline by default)
+# `local set` writes only to `.vaulter/local/*`; use `-e/--env` only for backend-aware operations.
+vaulter local set NEXT_PUBLIC_APP_NAME=Portal        --shared
+vaulter local set NODE_ENV=local                    --shared
+vaulter local set DATABASE_URL=postgres://...        -s api
+vaulter local set REDIS_URL=redis://...             -s api
+vaulter local set QUEUE_ENABLED::true               -s api
+vaulter local set WORKER_CONCURRENCY::4             -s web
+vaulter local pull --all                             # Generates .env for local run (all outputs)
+vaulter local diff                                # Review local overrides
+
+# 2) Share source of truth with team (backend sync)
+vaulter local push --all -e dev
+
+# 3) Team members pull and generate local envs
+vaulter local sync -e dev
+vaulter local pull --all
+
+# 4) Promote the same managed set to multiple environments
+for ENV in dev stg prd; do
+  echo "Deploying to $ENV"
+  vaulter plan -e "$ENV"
+  vaulter apply -e "$ENV" $( [ "$ENV" = "prd" ] && echo '--force' )
+done
+
+# 5) Run your scripts with vaulter-managed variables
+vaulter run -e dev -- pnpm start                  # Local run with local overrides
+vaulter run -e dev -s web -- pnpm --dir apps/web dev
+vaulter run -e dev -s api -- pnpm --dir apps/api lint
+vaulter run -e stg -s api -- pnpm --dir apps/api migrate
+vaulter run -e prd -- docker compose -f ./deploy/docker/docker-compose.yml up
+
+# 6) Export service-specific artifacts per environment
+# Config-like outputs
+vaulter export env -e dev --service api > apps/api/.env
+vaulter export env -e stg --service web > apps/web/.env
+vaulter export shell -e prd --service api > /tmp/api-env.sh
+
+# Kubernetes artifacts
+vaulter export k8s-secret -e dev --service api --name api-secrets
+vaulter export k8s-secret -e dev --service web --name web-secrets
+vaulter export k8s-secret -e stg --service api --name api-secrets
+vaulter export k8s-secret -e prd --service api --name api-secrets
+
+# Deployment formats
+vaulter export k8s-configmap -e prd --service api --name api-configmap
+vaulter export helm -e prd --service api --name api-values
+```
+
+> `--force` is required on `apply -e prd` and other production-like environments.
+
 ---
 
 ## 🔄 Development Workflow
@@ -91,18 +158,20 @@ apps/api/.env                # ❌ Gitignored - Generated output
 
 ```bash
 # 1. Start: Pull latest from backend + apply your local overrides
-vaulter local pull --all
+vaulter local pull
 
 # 2. Work: Add personal overrides (not shared with team)
 vaulter local set DEBUG::true                  # Shared override
-vaulter local set PORT::3001 -s api            # Service-specific
+vaulter local set PORT::3001                   # Service-specific (inferred from cwd in monorepo)
 
 # 3. Add new variable for team? Push to backend
-vaulter set NEW_VAR=value -e dev               # Add to backend
-vaulter sync push -e dev                       # Or push local .env
+vaulter local set NEW_VAR=value --shared        # Personal scratch pad
+vaulter local push                             # Share scratch locally with team
+vaulter plan -e dev                            # Preview changes (recommended)
+vaulter apply -e dev                           # Apply after approval
 
 # 4. Check: See what's different
-vaulter diff -e dev                            # Local vs backend
+vaulter diff -e dev                             # Local vs backend diff
 
 # 5. Promote: Clone to staging/production
 vaulter clone dev stg --dry-run                # Preview
@@ -138,37 +207,70 @@ vaulter clone dev stg                          # Execute
 
 ### Team Collaboration
 
-**New team member setup:**
+Team collaboration assumes one shared truth for each environment (backend) and private, local overrides per developer.
+
+**New team member setup (2 minutes):**
 ```bash
 git clone <repo>                    # Gets .vaulter/config.yaml
 export VAULTER_KEY_DEV=<from-team>  # Get key securely from team
-vaulter sync pull --dir -e dev      # Pull from backend → .vaulter/local/
+vaulter local sync -e dev           # Pull remote vars to .vaulter/local/
 vaulter local pull --all            # Generate .env files (offline)
 ```
 
-**Sharing a new variable:**
+**Why this is stable for teams**
+
+- `vaulter local set` is always a private, working-copy edit. It does **not** change what others consume by itself.
+- `vaulter local push` is how you publish team-visible changes from local overrides.
+- `vaulter local sync` is how others consume published changes.
+- Use environment-specific gates (`status`, `diff`, and `plan/apply`) before merging critical updates.
+
+**Recommended sharing flow (single variable):**
 ```bash
-# 1. Add locally
-vaulter local set NEW_FEATURE::enabled  # Shared config
+# 1) Add locally first
+vaulter local set --shared NEW_FEATURE::enabled  # Shared config
+vaulter local diff                                 # Verify local change before publishing
+
+# 2) Optional dry-run share preview
+vaulter local push --shared --dry-run -e dev         # Checks what would be pushed
 
-# 2. Push to backend (share with team)
-vaulter sync push --dir -e dev
+# 3) Share to backend (explicit approval step before running)
+vaulter local push --shared -e dev
 
-# 3. Notify team
-# "New var added, run: vaulter sync pull --dir && vaulter local pull --all"
+# 4) Notify team
+# "New var published. Run: vaulter local sync -e dev && vaulter local pull --all"
 ```
 
+**Monorepo service rule (recommended):**
+
+- Defaults are shared only when genuinely global.
+- Service behavior should live in service scope (`-s svc-*`) unless explicitly cross-service.
+- Keep service ownership rules documented in `.vaulter/config.yaml` (`policy`), so mistakes are prevented early.
+
+**Conflict resolution if two devs edit same key**
+
+```bash
+vaulter local diff -s <service>          # See your local delta
+vaulter local sync -e dev                # Pull latest from backend
+vaulter local pull --all                  # Rebuild outputs
+vaulter local diff -s <service>          # Re-check before pushing
+```
+
+If divergence remains:
+- Ask one owner to pause and re-publish.
+- Prefer `vaulter plan -e dev` + manual review for sensitive or cross-service keys.
+
+**Important:** Most `local` commands are local-only. Passing `-e/--env` is only needed when publishing or syncing with backend.
+
 ### MCP Tools for Workflow
 
 | Task | Tool |
 |:-----|:-----|
-| Check health | `vaulter_doctor` |
-| Pull with overrides | `vaulter_local_pull all=true` |
-| Set shared override | `vaulter_local_shared_set key="DEBUG" value="true"` |
-| Set service override | `vaulter_local_set key="PORT" value="3001" service="api"` |
-| See differences | `vaulter_local_diff` |
-| Clone environment | `vaulter_clone_env source="dev" target="stg"` |
-| Compare environments | `vaulter_compare source="dev" target="prd"` |
+| Check health | `vaulter_status action="scorecard"` |
+| Pull with overrides | `vaulter_local action="pull"` |
+| Set shared override | `vaulter_local action="shared-set" key="DEBUG" value="true"` |
+| Set service override | `vaulter_local action="set" key="PORT" value="3001"` |
+| See differences | `vaulter_diff` |
+| Compare environments | `vaulter_search source="dev" target="prd"` |
 
 ---
 
@@ -212,38 +314,40 @@ config() // Loads from .vaulter/local/ (configs.env + secrets.env)
 npx vaulter run -- pnpm dev
 
 # Or pull from backend first
-vaulter local pull --all
+vaulter local pull
 ```
 
 That's it! For most local development, vaulter is just a structured dotenv.
 
 ---
 
-## 🩺 Health Check - Doctor
+## 🩺 Health Check - Status
 
-**Always start with `vaulter doctor`** to diagnose your setup:
+**Always start with `vaulter status`** to diagnose your setup:
 
 ```bash
-vaulter doctor -e dev
+vaulter status -e dev
+vaulter status -e dev --offline
 ```
 
-Doctor performs **16 comprehensive checks**:
+Status performs **up to 18 checks** online, or a local-first subset in `--offline`.
 
 | Check | What It Does |
 |-------|--------------|
-| ✅ **Connection** | Tests backend connectivity |
+| ✅ **Connection** | Tests backend connectivity (skipped in `--offline`) |
 | ✅ **Latency** | Measures operation speed |
 | ✅ **Permissions** | Validates read/write/delete access |
 | ✅ **Encryption** | Tests encrypt → decrypt round-trip |
 | ✅ **Sync Status** | Compares local vs remote |
 | ✅ **Security** | Detects .env in git, weak keys |
+| ✅ **Scope Policy** | Checks `shared` vs `service` assignment rules |
 | ✅ **Perf Config** | Suggests cache/warmup/concurrency tuning |
-| ✅ **+9 more** | Config, project, environment, backend, keys, etc. |
+| ✅ **+8 more** | Config, project, environment, backend, keys, etc. |
 
 **Example output:**
 
 ```
-✓ ok: 14 | ⚠ warn: 1 | ✗ fail: 1
+✓ ok: 15 | ⚠ warn: 1 | ✗ fail: 1
 
 ✓ connection: connected (24 vars in dev)
 ✓ latency: read=45ms, list=67ms
@@ -266,17 +370,18 @@ For a quick pre-deploy validation in local/dev workflows:
 
 ```bash
 VAULTER_VERIFY_ENV=dev pnpm run verify:vaulter
+VAULTER_VERIFY_OFFLINE=0 VAULTER_VERIFY_REQUIRE_CONFIG=1 pnpm run verify:vaulter
 ```
 
 The script runs:
 
-- `vaulter doctor -e <env> -v`
-- `vaulter sync diff -e <env> --values`
+- `vaulter status -e <env> -v [--offline]` (offline by default)
+- `vaulter diff -e <env> --values`
 - `vaulter list -e <env>`
 
 It writes an execution log under `artifacts/vaulter-health/` for auditability.
 
-**For AI Agents:** Call `vaulter_doctor` once at the start of a new session (or when operations fail / environments change) to understand the current state before performing sensitive operations.
+**For AI Agents:** Call `vaulter_status action="scorecard"` once at the start of a new session (or when operations fail / environments change) to understand the current state before performing sensitive operations.
 
 See [docs/DOCTOR.md](docs/DOCTOR.md) for complete guide.
 
@@ -291,38 +396,52 @@ See [docs/DOCTOR.md](docs/DOCTOR.md) for complete guide.
 | `init` | Initialize project config |
 | `init --split` | Initialize with split mode (configs/secrets dirs) |
 
-### Variables (`var`)
+### Health
 
 | Command | Description |
 |:--------|:------------|
-| `var get <key> -e <env>` | Get a variable |
-| `var set KEY=val -e <env>` | Set secret (encrypted) |
-| `var set KEY::val -e <env>` | Set config (plain text) |
-| `var set KEY:=123 -e <env>` | Set typed secret (number/boolean) |
-| `var delete <key> -e <env>` | Delete a variable |
-| `var list -e <env>` | List all variables |
+| `status -e <env>` | Full diagnostic report with checks and suggestions |
+
+### Mutations (`change`)
+
+| Command | Description |
+|:--------|:------------|
+| `change set KEY=val -e <env>` | Set secret (encrypted) |
+| `change set KEY::val -e <env>` | Set config (plain text) |
+| `change set KEY:=123 -e <env>` | Set typed secret (number/boolean) |
+| `change delete <key> -e <env>` | Delete variable |
+| `change move <key> --from <scope> --to <scope> -e <env>` | Move/copy variable between scopes |
+| `change import -f <file> -e <env>` | Import variables from file |
+| `list -e <env>` | List all variables |
 
 **Set syntax**: `=` encrypted secret · `::` plain config · `:=` typed secret
 
-### Sync
+In monorepo mode, when `--service` is resolved, one of `--from` or `--to` can be omitted and inferred from the active service.
+
+### Plan & Apply
 
 | Command | Description |
 |:--------|:------------|
-| `sync merge -e <env>` | Bidirectional merge (default) |
-| `sync pull -e <env>` | Download from backend to outputs |
-| `sync pull --dir -e <env>` | Download to `.vaulter/{env}/` directory |
-| `sync push -e <env>` | Upload .env file to backend |
-| `sync push --dir -e <env>` | Upload `.vaulter/{env}/` directory to backend |
-| `sync push --prune -e <env>` | Upload, delete remote-only vars |
-| `sync diff -e <env>` | Show differences without changes |
+| `plan -e <env>` | Compute diff local vs backend, generate plan artifact |
+| `apply -e <env>` | Execute plan, push changes to backend |
+| `diff -e <env>` | Quick diff without plan artifacts |
+| `plan --dir -e <env>` | Plan from `.vaulter/{env}/` directory |
+| `plan [--plan-output <file>] -e <env>` | Write plan artifact (`.json` + `.md`). If `--plan-output` is omitted, defaults to `artifacts/vaulter-plans/<project>-<env>-<timestamp>.*` |
+
+### Recommended daily path
+
+- `vaulter local pull` → `vaulter local set` → `vaulter local push` (when ready)
+- `vaulter change set` → `vaulter change move` → `vaulter plan -e <env>` → `vaulter apply -e <env>`
+- `vaulter plan -e <env>` → validate → `vaulter apply -e <env>`
+- `vaulter status -e <env>` for quick pre-flight health check
 
 ### Export
 
 | Command | Description |
 |:--------|:------------|
 | `export shell -e <env>` | Export for shell `eval $(...)` |
-| `export k8s-secret -e <env>` | Generate Kubernetes Secret |
-| `export k8s-configmap -e <env>` | Generate Kubernetes ConfigMap |
+| `export k8s-secret -e <env>` | Generate Kubernetes Secret (sensitive vars only) |
+| `export k8s-configmap -e <env>` | Generate Kubernetes ConfigMap (config vars only) |
 | `export helm -e <env>` | Generate Helm values.yaml |
 | `export terraform -e <env>` | Generate Terraform .tfvars |
 | `export docker -e <env>` | Docker env-file format |
@@ -381,6 +500,30 @@ npx vaulter run -e prd -- pnpm build
 npx vaulter run -e dev -s api -- pnpm start
 ```
 
+### Run scripts via package.json
+
+Use `vaulter run` directly in your npm scripts to keep variables centralized and explicit.
+
+```json
+{
+  "scripts": {
+    "dev:web": "vaulter run -e dev -s web -- pnpm --dir apps/web dev",
+    "lint:api": "vaulter run -e dev -s api -- pnpm --dir apps/api lint",
+    "migrate:api:stg": "vaulter run -e stg -s api -- pnpm --dir apps/api run migrate",
+    "deploy:api:prd": "vaulter run -e prd -s api -- pnpm --dir apps/api build && vaulter export k8s-secret -e prd -s api --name api-secrets"
+  }
+}
+```
+
+```bash
+npm run dev:web
+npm run lint:api
+npm run migrate:api:stg
+```
+
+The important part is that `vaulter run` stays as the first command so variable resolution and scope resolution
+happen before your script command.
+
 The `run` command auto-detects the environment (local, CI, K8s) and loads the appropriate files before executing your command.
 
 > Run `vaulter --help` or `vaulter <command> --help` for all options.
@@ -499,10 +642,10 @@ encryption:
 **Example flow:**
 ```bash
 # Set shared var (uses dev key because shared_key_environment: dev)
-vaulter var set LOG_LEVEL=debug -e dev --shared
+vaulter change set LOG_LEVEL=debug -e dev --scope shared
 
 # Read shared var from prd (still uses dev key for shared vars)
-vaulter var list -e prd --shared  # Works! Uses dev key for shared
+vaulter list -e prd --shared  # Works! Uses dev key for shared
 ```
 
 ---
@@ -533,6 +676,20 @@ audit:
   enabled: true
   retention_days: 90
 
+scope_policy:
+  mode: warn
+  inherit_defaults: true
+  rules:
+    - name: api-keys-service
+      pattern: '^API_'
+      expected_scope: service
+      expected_service: svc-app
+      reason: 'API_* vars are service-owned'
+    - name: app-url-shared-default
+      pattern: '^APP_.*_URL$'
+      expected_scope: shared
+      reason: 'URL variables stay shared by default'
+
 # Local development files (see "Local vs Deploy Structure" below)
 # local: .vaulter/local/
 
@@ -581,7 +738,7 @@ Vaulter separates **local development** from **deployment** configurations:
 | `local/configs.env` | Developer's machine | Ignored | Non-sensitive local vars |
 | `local/secrets.env` | Developer's machine | Ignored | Sensitive local secrets |
 | `deploy/configs/*.env` | CI/CD configs | Committed | Non-sensitive (PORT, HOST, LOG_LEVEL) |
-| `deploy/secrets/*.env` | CI/CD secrets | Ignored | Pulled via `vaulter sync pull` |
+| `deploy/secrets/*.env` | CI/CD secrets | Ignored | Pulled via `vaulter local sync` |
 
 **Gitignore:**
 
@@ -754,7 +911,8 @@ You can also use the CLI directly:
     AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
     AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
   run: |
-    npx vaulter sync pull -e prd
+    npx vaulter local sync -e prd
+    npx vaulter local pull -e prd
     npx vaulter run -e prd -- pnpm build
 ```
 
@@ -797,8 +955,8 @@ Auto-detects NX, Turborepo, Lerna, pnpm, Yarn workspaces, Rush.
 
 ```bash
 vaulter service list                       # List discovered services
-vaulter sync push -e dev -s api            # Push specific service
-vaulter sync push -e dev --shared          # Push shared variables
+vaulter plan -e dev -s api                 # Plan changes for specific service
+vaulter apply -e dev -s api               # Apply planned changes
 vaulter export shell -e dev -s api         # Export with shared inheritance
 vaulter export shell -e dev --shared       # Export only shared variables
 ```
@@ -864,7 +1022,7 @@ shared:
 
 ```bash
 # Pull to all outputs at once
-vaulter sync pull --all
+vaulter local pull --all
 
 # Result:
 # ✓ web: apps/web/.env.local (5 vars)
@@ -876,10 +1034,10 @@ vaulter sync pull --all
 
 ```bash
 # Pull only web
-vaulter sync pull --output web
+vaulter local pull --output web
 
 # Preview without writing
-vaulter sync pull --all --dry-run
+vaulter local pull --all --dry-run
 ```
 
 ### How It Works
@@ -890,7 +1048,7 @@ vaulter sync pull --all --dry-run
 │  DATABASE_URL, JWT_SECRET, NEXT_PUBLIC_API, LOG_LEVEL   │
 └────────────────────────┬────────────────────────────────┘
                          │
-              vaulter sync pull --all
+              vaulter local pull --all
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
@@ -929,17 +1087,19 @@ outputs:
 
 ## Local Overrides (Dev Environment) - OFFLINE FIRST
 
-**`vaulter local pull` is 100% OFFLINE** - no backend calls!
+**`vaulter local pull` and local `.env` generation are 100% OFFLINE** - no backend calls.
 
-Works entirely from local files in `.vaulter/local/`. Perfect for local development where you want to work offline and sync later.
+Works entirely from local files in `.vaulter/local/`. This is the primary workflow for day-to-day development: edit local overrides, run `vaulter local pull`, and only sync when needed.
 
 ### Quick Reference
 
 | Command | What it does | Backend? |
 |---------|--------------|----------|
-| `vaulter local pull --all` | Generate .env files from local | ❌ OFFLINE |
+| `vaulter local pull` | Generate .env files from local | ❌ OFFLINE |
 | `vaulter local push --all` | Send local → backend | ✅ Backend |
 | `vaulter local sync` | Download backend → local | ✅ Backend |
+| `vaulter local set` | Write local override to `.vaulter/local/` | ❌ OFFLINE |
+| `vaulter local diff` | Compare local overrides vs base env | ❌ OFFLINE |
 
 ### Workflow
 
@@ -947,7 +1107,7 @@ Works entirely from local files in `.vaulter/local/`. Perfect for local developm
 ┌─────────────────────────────────────────────────────┐
 │              LOCAL DEVELOPMENT                       │
 │  1. Edit .vaulter/local/*.env                       │
-│  2. vaulter local pull --all  → Generate .env       │
+│  2. vaulter local pull       → Generate .env       │
 │  3. Develop...                                       │
 └─────────────────────────────────────────────────────┘
                          ↓
@@ -960,10 +1120,12 @@ Works entirely from local files in `.vaulter/local/`. Perfect for local developm
 │              NEW TEAM MEMBER                         │
 │  1. git clone <repo>                                │
 │  2. vaulter local sync     → Download from backend  │
-│  3. vaulter local pull --all → Generate .env        │
+│  3. vaulter local pull      → Generate .env        │
 └─────────────────────────────────────────────────────┘
 ```
 
+For monorepos, use `--service <name>` on `local set`, `local delete`, `local diff`, and `local push` (without `--all`), unless the CLI can infer the service from your current directory (or the monorepo has only one service).
+
 ### File Structure
 
 ```
@@ -997,11 +1159,13 @@ For each output target, vaulter merges:
 # === EDIT LOCALLY ===
 vaulter local set --shared DEBUG::true     # shared config
 vaulter local set --shared API_KEY=xxx     # shared secret
-vaulter local set PORT::3001 -s web        # service config
+vaulter local set PORT::3001                # service config (inferred from cwd in monorepo)
 vaulter local set DB_URL=xxx -s api        # service secret
+# In service directories, `-s` is usually auto-inferred.
+# If the repo has only one service, `-s` is inferred automatically too.
 
 # === GENERATE .ENV FILES [OFFLINE] ===
-vaulter local pull --all
+vaulter local pull
 # Output: "svc-auth: 23 vars (21 shared + 2 service)"
 
 # === SHARE WITH TEAM ===
@@ -1009,7 +1173,7 @@ vaulter local push --all                   # Upload entire structure
 
 # === GET TEAM'S CHANGES ===
 vaulter local sync                         # Download from backend
-vaulter local pull --all                   # Generate .env files
+vaulter local pull                        # Generate .env files
 
 # === OTHER ===
 vaulter local diff                         # Show differences
@@ -1045,10 +1209,10 @@ NODE_ENV=production
 
 ```bash
 # Section-aware pull (default)
-vaulter local pull --all
+vaulter local pull
 
 # Overwrite entire file (ignores sections)
-vaulter local pull --all --overwrite
+vaulter local pull --overwrite
 ```
 
 **Programmatic API:**
@@ -1271,7 +1435,7 @@ const result = await loadRuntime({
 
 ## MCP Server
 
-Claude AI integration via Model Context Protocol. **53 tools, 6 resources, 12 prompts.**
+Claude AI integration via Model Context Protocol. **17 Tools | 4 Resources | 5 Prompts.**
 
 ```bash
 vaulter mcp
@@ -1290,58 +1454,52 @@ vaulter mcp
 }
 ```
 
-### Tools (53)
-
-| Category | Tools |
-|:---------|:------|
-| **Core (5)** | `vaulter_get`, `vaulter_set`, `vaulter_delete`, `vaulter_list`, `vaulter_export` |
-| **Batch (3)** | `vaulter_multi_get`, `vaulter_multi_set`, `vaulter_multi_delete` |
-| **Sync (3)** | `vaulter_sync`, `vaulter_pull`, `vaulter_push` |
-| **Analysis (2)** | `vaulter_compare`, `vaulter_search` |
-| **Status (2)** | `vaulter_status`, `vaulter_audit_list` |
-| **K8s (2)** | `vaulter_k8s_secret`, `vaulter_k8s_configmap` |
-| **IaC (2)** | `vaulter_helm_values`, `vaulter_tf_vars` |
-| **Keys (6)** | `vaulter_key_generate`, `vaulter_key_list`, `vaulter_key_show`, `vaulter_key_export`, `vaulter_key_import`, `vaulter_key_rotate` |
-| **Monorepo (5)** | `vaulter_init`, `vaulter_scan`, `vaulter_services`, `vaulter_shared_list`, `vaulter_inheritance_info` |
-| **Categorization (1)** | `vaulter_categorize_vars` |
-| **Dangerous (1)** | `vaulter_nuke_preview` |
-| **Utility (4)** | `vaulter_copy`, `vaulter_rename`, `vaulter_promote_shared`, `vaulter_demote_shared` |
-| **Local Overrides (8)** | `vaulter_local_pull`, `vaulter_local_set`, `vaulter_local_delete`, `vaulter_local_diff`, `vaulter_local_status`, `vaulter_local_shared_set`, `vaulter_local_shared_delete`, `vaulter_local_shared_list` |
-| **Snapshot (3)** | `vaulter_snapshot_create`, `vaulter_snapshot_list`, `vaulter_snapshot_restore` |
-| **Versioning (3)** | `vaulter_list_versions`, `vaulter_get_version`, `vaulter_rollback` |
-| **Diagnostic (3)** | `vaulter_doctor`, `vaulter_clone_env`, `vaulter_diff` |
-
-### Resources (6)
+### Tools (17)
+
+> **Tool Architecture:** Each tool is action-based (one tool per domain with `action` parameter).
+
+| Category | Tool | Actions / Description |
+|:---------|:-----|:---------------------|
+| **Mutation Flow** | `vaulter_change` | set, delete, move, import (writes local state only) |
+| | `vaulter_plan` | Compute diff local vs backend, generate plan artifact |
+| | `vaulter_apply` | Execute plan, push changes to backend |
+| | `vaulter_run` | Execute command with loaded variables |
+| **Read** | `vaulter_get` | Get single var or multi-get via `keys[]` |
+| | `vaulter_list` | List vars with optional filter |
+| | `vaulter_search` | Search by pattern or compare environments |
+| | `vaulter_diff` | Quick diff without plan artifacts |
+| **Status** | `vaulter_status` | scorecard, vars, audit, drift, inventory |
+| **Export** | `vaulter_export` | k8s-secret, k8s-configmap, helm, terraform, env, shell, json |
+| **Keys** | `vaulter_key` | generate, list, show, export, import, rotate |
+| **Local Dev** | `vaulter_local` | pull, push, push-all, sync, set, delete, diff, status, shared-set, shared-delete, shared-list |
+| **Backup** | `vaulter_snapshot` | create, list, restore, delete |
+| | `vaulter_versions` | list, get, rollback |
+| **Setup** | `vaulter_init` | Initialize project |
+| | `vaulter_services` | Discover monorepo services |
+| **Danger** | `vaulter_nuke` | Preview backend deletion (CLI-only execution) |
+
+### Resources (4)
 
 Static data views (no input required). For actions with parameters, use tools.
 
 | URI | Description |
 |:----|:------------|
-| `vaulter://instructions` | **Read first!** How vaulter stores data (s3db.js architecture) |
+| `vaulter://instructions` | **Read first!** s3db.js architecture + tool overview |
 | `vaulter://tools-guide` | Which tool to use for each scenario |
-| `vaulter://monorepo-example` | Complete monorepo isolation example with var counts |
-| `vaulter://mcp-config` | MCP settings sources (priority chain) |
 | `vaulter://config` | Project configuration (YAML) |
 | `vaulter://services` | Monorepo services list |
 
-### Prompts (12)
+### Prompts (5)
 
 Pre-configured workflows for common tasks.
 
 | Prompt | Description |
 |:-------|:------------|
 | `setup_project` | Initialize new vaulter project |
-| `migrate_dotenv` | Migrate existing .env files |
 | `deploy_secrets` | Deploy to Kubernetes |
 | `compare_environments` | Compare dev vs prd |
-| `security_audit` | Audit secrets for issues |
 | `rotation_workflow` | Check/rotate/report on rotation |
-| `shared_vars_workflow` | Manage monorepo shared vars |
-| `batch_operations` | Multi-set/get/delete operations |
-| `copy_environment` | Copy variables between environments |
-| `sync_workflow` | Sync local files with remote backend |
-| `monorepo_deploy` | Complete monorepo setup with isolation |
-| `local_overrides_workflow` | Manage local dev overrides (shared + service) |
+| `local_dev_workflow` | Manage local dev overrides (shared + service) |
 
 > **Full MCP documentation:** See [docs/MCP.md](docs/MCP.md) for complete tool reference with parameters.
 

package/dist/cli/commands/apply.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Vaulter `apply` Command
+ *
+ * Executes the last plan, pushing changes to the backend.
+ * If no plan exists or plan is stale, auto-plans first.
+ *
+ * Usage:
+ *   vaulter apply -e dev                  Apply latest plan (auto-plan if needed)
+ *   vaulter apply -e prd --force          Apply to production (requires --force)
+ *   vaulter apply -e dev --dry-run        Show what would be applied
+ *   vaulter apply -e dev --prune          Include remote-only deletions
+ */
+import type { VarContext } from './change.js';
+export declare function runApply(context: VarContext): Promise<void>;
+//# sourceMappingURL=apply.d.ts.map

package/dist/cli/commands/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAc7C,wBAAsB,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA8GjE"}