Fix/template chagne instance type (#38)

* fix: template wizard uses instance-types API, not availability

Templates are saved configs — filtering by real-time availability
doesn't make sense. Instance type and location steps now use the
instance-types and locations APIs in template mode, showing all
options. Location is optional in templates (skip = decide at deploy
time). Deploy mode is unchanged.

Also improves UX when deploying from a location-less template: the
wizard now prompts for location instead of silently defaulting to
FIN-01, and shows a clear error when no locations are available.

Author: hi-lei

AGENTS.md

@@ -7,11 +7,13 @@ Read `CLAUDE.md` first. This file defines how you execute, not what the project
 Do NOT write code until you have completed all steps below. No exceptions.
 
 **Step 1 — Read** (always, every task):
-1. `CLAUDE.md` (root) — architecture, conventions, pricing rules
-2. `CLAUDE.md` in the target command directory (e.g. `cmd/vm/CLAUDE.md`) — domain gotchas
-3. `README.md` in the target command directory — usage, flags, examples
+1. `CLAUDE.md` (root) — architecture, conventions, pricing rules, per-command doc index
+2. `cmd/<domain>/CLAUDE.md` in the target command directory — domain knowledge, gotchas, edge cases
+3. `cmd/<domain>/README.md` in the target command directory — usage examples, flags, architecture
 4. `.ai/skills/new-command.md` if adding or modifying a command
 
+Per-command docs exist in: `auth`, `vm`, `template`, `volume`, `sshkey`, `startupscript`, `update`, `settings`. For commands without docs, read the source files directly.
+
 **Step 2 — Verify** (always):
 5. Run `make test` to confirm the repo is green before you start
 

CLAUDE.md

@@ -20,11 +20,38 @@ cmd/verda/                    # Entrypoint
 internal/verda-cli/
   cmd/cmd.go                  # Root command, command groups
   cmd/util/                   # Factory, IOStreams, helpers, pricing, hostname
-  cmd/<domain>/               # One dir per domain (vm, volume, auth, skills, ...)
+  cmd/<domain>/               # One dir per domain (see per-command docs below)
+    CLAUDE.md                 # Domain knowledge, gotchas, edge cases
+    README.md                 # Usage examples, flags, architecture notes
   options/                    # Global CLI options, credentials
 internal/skills/              # Embedded AI skill files (go:embed)
 ```
 
+### Per-Command Documentation
+
+Each command directory has its own `CLAUDE.md` (domain knowledge) and `README.md` (usage/architecture). These are the source of truth for command-specific behavior.
+
+| Directory | Docs | Description |
+|-----------|------|-------------|
+| `cmd/vm/` | CLAUDE.md, README.md | VM create/list/describe/action, wizard, templates |
+| `cmd/template/` | CLAUDE.md, README.md | Template create/edit/list/show/delete |
+| `cmd/auth/` | CLAUDE.md, README.md | Login, logout, show credentials |
+| `cmd/volume/` | CLAUDE.md, README.md | Volume lifecycle, trash, actions |
+| `cmd/sshkey/` | CLAUDE.md, README.md | SSH key management |
+| `cmd/startupscript/` | CLAUDE.md, README.md | Startup script management |
+| `cmd/update/` | CLAUDE.md, README.md | CLI self-update |
+| `cmd/settings/` | CLAUDE.md, README.md | CLI settings management |
+| `cmd/availability/` | — | Instance availability by location |
+| `cmd/cost/` | — | Balance, running costs, estimates |
+| `cmd/images/` | — | OS image listing |
+| `cmd/instancetypes/` | — | Instance type catalog |
+| `cmd/locations/` | — | Datacenter locations |
+| `cmd/status/` | — | Status dashboard |
+| `cmd/ssh/` | — | SSH into instances |
+| `cmd/mcp/` | — | MCP server |
+| `cmd/skills/` | — | AI skills management |
+| `cmd/completion/` | — | Shell completions |
+
 ### Core Patterns
 
 - **Factory** (`cmd/util/factory.go`): DI for Prompter, Status, VerdaClient, Debug, AgentMode, OutputFormat
@@ -69,12 +96,12 @@ internal/skills/              # Embedded AI skill files (go:embed)
 
 ## Before Editing Any Command
 
-1. Read the **nearest** `CLAUDE.md` in the command directory (e.g. `cmd/vm/CLAUDE.md`)
-2. Read the **nearest** `README.md` for usage examples and flag details
+1. Read the **nearest** `CLAUDE.md` in the command directory (e.g. `cmd/vm/CLAUDE.md`) — domain knowledge, gotchas, edge cases
+2. Read the **nearest** `README.md` in the command directory — usage examples, flags, architecture
 3. Read `.ai/skills/new-command.md` for the full checklist when adding/modifying commands
 4. If touching pricing, auth, or agent-mode: plan first, don't code immediately
 
-Per-command docs are auto-maintained by a pre-commit hook.
+Per-command docs are auto-maintained by `/update-command-knowledge` skill.
 Manual update: `claude -p "/update-command-knowledge --all" --model sonnet --dangerously-skip-permissions`
 
 ## Thinking Depth

internal/skills/files/verda-reference.md

@@ -96,13 +96,17 @@ Tell user to run in their terminal:
 
 | Command | Notes |
 |---------|-------|
-| `verda template list -o json` | Lists saved templates |
-| `verda template show vm/<name> -o json` | Note: `vm/` prefix required |
+| `verda template list -o json` | Fields: `resource`, `name`, `description` |
+| `verda template show vm/<name> -o json` | Fields: `InstanceType`, `Location`, `Image`, `SSHKeys[]`, `HostnamePattern`, `Description`. Note: `vm/` prefix required |
 | `verda template delete vm/<name>` | Confirm first |
 | `verda template create` | Interactive — tell user to run |
-| `verda template edit <name>` | Interactive — tell user to run |
+| `verda template edit <name>` | Interactive field editor — tell user to run |
 
-Deploy: `verda --agent vm create --from <name> --hostname <name> --wait --wait-timeout 2m -o json`
+Deploy from template (flags override template values):
+```bash
+verda --agent vm create --from <name> --hostname <name> --wait --wait-timeout 2m -o json
+verda --agent vm create --from <name> --location FIN-03 -o json   # override location
+```
 Hostname patterns: `{random}` → random words, `{location}` → location code
 
 ## Volumes

internal/verda-cli/cmd/template/CLAUDE.md

@@ -24,8 +24,8 @@ All fields except `resource` are optional. Stored at `~/.verda/templates/<resour
 | `contract` | string | `"PAY_AS_YOU_GO"`, `"SPOT"`, `"LONG_TERM"` |
 | `kind` | string | `"GPU"` or `"CPU"` (lowercase in template, case-insensitive in matching) |
 | `instance_type` | string | e.g. `"1V100.6V"` |
-| `location` | string | e.g. `"FIN-01"` |
-| `image` | string | OS image slug or ID |
+| `location` | string | Optional. e.g. `"FIN-01"`. If omitted, wizard prompts at deploy time |
+| `image` | string | OS image **name** (resolved to ID at deploy time) |
 | `os_volume_size` | int | GiB |
 | `storage` | []StorageSpec | Each has `type` and `size` |
 | `storage_skip` | bool | Skip storage step in wizard |
@@ -79,8 +79,8 @@ The `template edit` command uses a field menu approach (not the full wizard):
 ### Edit field editors
 - **Billing Type**: static select (on-demand / spot). Clears contract when switching to spot.
 - **Kind**: static select (gpu / cpu)
-- **Instance Type**: API call to `InstanceTypes.Get`, filtered by current kind, shows price
-- **Location**: API call to `Locations.Get`
+- **Instance Type**: API call to `InstanceTypes.Get` (not availability), filtered by current kind, shows price
+- **Location**: API call to `Locations.Get`, includes "None (decide at deploy time)" to clear location
 - **Image**: API call to `Images.Get`, excludes cluster images
 - **OS Volume Size**: text input with current value as default
 - **SSH Keys**: API call to `SSHKeys.GetAllSSHKeys`, multi-select with current keys pre-selected
@@ -108,6 +108,9 @@ Displays all template fields, including those previously hidden:
 
 - **Import cycle**: `cmd/template/` cannot import `cmd/vm/` for the Template type (circular dependency). Shared types live in `internal/verda-cli/template/`, re-exported by `cmd/template/types.go` via type aliases and `var` bindings.
 - **`billingTypeSet` / `locationSet` flags**: Needed because `IsSet` in the wizard can't distinguish `"on-demand"` (falsy `IsSpot=false`) from "unset". When a template sets billing type or location, these booleans are set to `true` so the wizard skips those steps.
+- **Template without location triggers wizard**: When `--from` is used and the template has no location (`!opts.locationSet`), `resolveCreateInputs` triggers the wizard so the user is prompted for location instead of silently defaulting to FIN-01.
+- **Template instance type/location use different APIs**: Template wizard (create) uses instance-types API and locations API directly. Deploy wizard uses availability API to filter. Template edit also uses instance-types and locations APIs directly.
+- **Template error message**: `Resolve()` now shows `template name is required — template "X" not found` with guidance to run `verda template list` or use `--from` interactively.
 - **`NoOptDefVal` on `--from` flag**: Set to `" "` (space) so `--from` without a value is recognized as "flag changed but empty". When the user writes `verda vm create --from gpu-training`, cobra parses `gpu-training` as a positional arg; `RunE` recombines it into `opts.From`.
 - **Startup script "None (skip)" label**: The wizard presents "None (skip)" as a selectable option. Previously, this label text was captured as the script name. Fixed by checking `Value != ""` before storing the name.
 - **`ensurePricingCache`**: The confirm-deploy step calls this (with parent context, not `context.Background()`) to fetch pricing when the cache is empty from template pre-fill.

internal/verda-cli/cmd/template/README.md

@@ -28,7 +28,7 @@ verda template create
 verda template create gpu-training
 ```
 
-The create command runs the VM wizard in **template mode** -- the same 10 configuration steps (billing type through startup script) but without hostname, description, or confirm-deploy. The resulting settings are saved to disk.
+The create command runs the VM wizard in **template mode** -- the same 10 configuration steps (billing type through startup script) but without hostname, description, or confirm-deploy. In template mode, instance types come from the instance-types API (not filtered by availability) and location is optional ("None — decide at deploy time"). The resulting settings are saved to disk.
 
 ### Edit
 
@@ -40,7 +40,7 @@ verda template edit
 verda template edit vm/gpu-training
 ```
 
-Shows a menu of all template fields with their current values. Pick a field to change, edit it with the appropriate prompt (static choices for simple fields, API-backed selection for instance type/location/image/SSH keys/startup script). Repeat until "Save & exit".
+Shows a menu of all template fields with their current values. Pick a field to change, edit it with the appropriate prompt (static choices for simple fields, API-backed selection for instance type/location/image/SSH keys/startup script). Location includes a "None (decide at deploy time)" option to clear the value. Repeat until "Save & exit".
 
 ### List
 
@@ -101,8 +101,8 @@ billing_type: on-demand          # on-demand or spot
 contract: PAY_AS_YOU_GO
 kind: GPU                        # GPU or CPU
 instance_type: 1V100.6V
-location: FIN-01
-image: ubuntu-24.04-cuda-12.8
+location: FIN-01                  # optional — omit to prompt at deploy time
+image: ubuntu-24.04-cuda-12.8     # stored by name, resolved to ID at deploy time
 os_volume_size: 200              # GiB
 storage:
   - type: NVMe
@@ -124,11 +124,17 @@ verda vm create --from gpu-training              # load by name
 verda vm create --from ./my-template.yaml        # load from file path
 verda vm create --from                           # pick from list (interactive)
 verda vm create --from gpu-training --hostname my-vm --description "test"
+
+# Override template values with flags
+verda vm create --from gpu-training --location FIN-03
+verda vm create --from gpu-training --hostname my-vm --os-volume-size 200
 ```
 
+Flags passed alongside `--from` override the template values.
+
 ### Flow
 
-1. Template values pre-fill the wizard's `createOptions`
+1. Template values pre-fill the wizard's `createOptions` (CLI flags take precedence — they are parsed first)
 2. A summary of template values is printed to stderr
 3. SSH keys and startup scripts are resolved by name to ID via the API; unresolved names produce warnings (no longer silently swallowed)
 4. Only unfilled steps are prompted (hostname, description, confirm-deploy are always prompted; other steps only if the template didn't fill them)

internal/verda-cli/cmd/template/edit.go

@@ -301,16 +301,20 @@ func editLocation(ctx context.Context, f cmdutil.Factory, t *Template) error {
 		return err
 	}
 
-	choices := make([]string, len(locations))
-	for i, loc := range locations {
-		choices[i] = loc.Code
+	choices := []string{"None (decide at deploy time)"}
+	for _, loc := range locations {
+		choices = append(choices, loc.Code)
 	}
 
 	idx, selErr := f.Prompter().Select(ctx, "Location", choices)
 	if selErr != nil {
 		return nil //nolint:nilerr // user canceled
 	}
-	t.Location = locations[idx].Code
+	if idx == 0 {
+		t.Location = ""
+	} else {
+		t.Location = locations[idx-1].Code
+	}
 	return nil
 }
 

internal/verda-cli/cmd/vm/CLAUDE.md

@@ -7,7 +7,7 @@
   - `vm.go` -- Parent command, registers subcommands and shortcuts
   - `create.go` -- Create command, flags, `createOptions` struct, request building, validation
   - `wizard.go` -- 13 wizard step definitions, `WizardMode`, `RunTemplateWizard`, step Defaults
-  - `wizard_cache.go` -- `apiCache`, `ensurePricingCache`, pricing helpers, instance type utils
+  - `wizard_cache.go` -- `apiCache`, `fetchLocations`, `loadAllLocations`/`loadAvailableLocations`, `ensurePricingCache`, pricing helpers, instance type utils
   - `wizard_subflows.go` -- SSH key, startup script, storage interactive sub-flows
   - `wizard_summary.go` -- `renderDeploymentSummary` (accepts `io.Writer`)
   - `template_apply.go` -- Template loading, applying, name resolution with warnings
@@ -83,7 +83,10 @@ startup-script -> hostname -> description -> confirm-deploy
 
 - Steps with `DependsOn` re-run their Loader when dependencies change
 - `contract` step: `ShouldSkip` returns true for spot billing
+- `instance-type` step: accepts `WizardMode`. Deploy mode filters by real-time availability; template mode shows all instance types from the instance-types API (no availability filtering)
+- `location` step: accepts `WizardMode`. Deploy mode shows only locations where the instance type is available; template mode shows all locations with a "None (decide at deploy time)" skip option. Deploy mode returns a clear error when no locations are available for the instance type
 - `location` step: `IsSet` treats default `FIN-01` as unset (so wizard prompts)
+- `location` step: `Required` is dynamic — true in deploy mode, false in template mode
 - `storage`, `ssh-keys`, `startup-script` steps: manage values directly in Loader (Setter/Resetter are no-ops), include inline sub-flows for creating new resources via API
 - `confirm-deploy` step: renders deployment summary with full cost breakdown via `renderDeploymentSummary(w, opts, cache)`
 - Steps have `Default` functions that return current `opts` values for pre-selection (used when `--from` pre-fills values)
@@ -98,8 +101,9 @@ startup-script -> hostname -> description -> confirm-deploy
 
 ## Gotchas & Edge Cases
 
-- **Wizard triggers when ANY of instance-type, os, or hostname is missing** -- not all three. Providing two of three still launches the wizard.
+- **Wizard triggers when ANY of instance-type, os, or hostname is missing** -- not all three. Providing two of three still launches the wizard. Also triggers when `--from` was used but the template had no location (`templateWithoutLocation` check in `resolveCreateInputs`).
 - **Location default quirk**: `LocationCode` defaults to `FIN-01` in createOptions, but the wizard's `IsSet` returns false for `FIN-01` specifically, so the wizard always prompts for location even when the default is in effect.
+- **Flags override template values**: When `--from` is used alongside other flags (e.g. `--hostname`, `--location`), flags are parsed first, then `applyTemplate` only overwrites empty fields. CLI flags take precedence.
 - **apiCache invalidation**: Cache is invalidated when `isSpot` changes (user switches billing type), because availability differs between spot and on-demand.
 - **Lazy client resolution**: `clientFunc` defers credential resolution until the first API-dependent wizard step fires. Early steps (billing-type, kind, text inputs) run without credentials.
 - **Hidden flag aliases**: `--type`, `--image`, `--ssh-key-id`, `--startup-script-id`, `--spot` are hidden aliases for their primary flags.

internal/verda-cli/cmd/vm/README.md

@@ -29,6 +29,10 @@ verda vm create
 # From a saved template (only prompts for hostname + confirm)
 verda vm create --from gpu-training
 
+# From a template, override specific fields with flags
+verda vm create --from gpu-training --location FIN-03
+verda vm create --from gpu-training --hostname my-vm --os-volume-size 200
+
 # Pick template from list
 verda vm create --from
 
@@ -97,8 +101,8 @@ The wizard launches automatically when any of `--instance-type`, `--os`, or `--h
 1. Billing type (On-Demand or Spot)
 2. Contract period (skipped for Spot)
 3. Compute type (GPU or CPU)
-4. Instance type (filtered by kind and availability)
-5. Datacenter location (filtered by instance type availability)
+4. Instance type (deploy mode: filtered by kind and availability; template mode: all types from instance-types API)
+5. Datacenter location (deploy mode: filtered by instance type availability; template mode: all locations, optional)
 6. OS image (cluster images excluded)
 7. OS volume size (default: 50 GiB)
 8. Storage -- add new volumes, attach existing detached volumes, or skip
@@ -135,7 +139,7 @@ Destructive actions (Shutdown, Force shutdown, Delete) show confirmation prompts
 - **vm.go** -- Parent command definition, registers subcommands and shortcut commands
 - **create.go** -- `vm create` command, flag definitions, `createOptions` struct (with 5-stage mutation lifecycle), request building, contract normalization, volume spec parsing, kind validation
 - **wizard.go** -- 13 wizard step definitions using the wizard engine; `clientFunc` lazy client pattern; `WizardMode` (Deploy vs Template); `RunTemplateWizard`; step Default functions for pre-selection
-- **wizard_cache.go** -- `apiCache` struct for deduplicating API calls, `ensurePricingCache`, pricing helpers (`volumeHourlyPrice`, `instanceUnits`), instance type matching (`matchesKind`, `formatGPU`, `formatMemory`)
+- **wizard_cache.go** -- `apiCache` struct for deduplicating API calls, `fetchLocations` (locations without availability), `loadAllLocations`/`loadAvailableLocations` (extracted location loaders), `ensurePricingCache`, pricing helpers (`volumeHourlyPrice`, `instanceUnits`), instance type matching (`matchesKind`, `formatGPU`, `formatMemory`)
 - **wizard_subflows.go** -- Interactive sub-flows for SSH key creation, startup script creation, storage volume management; choice builders for multi-select prompts
 - **wizard_summary.go** -- `renderDeploymentSummary` with full cost breakdown (accepts `io.Writer`)
 - **template_apply.go** -- `resolveCreateInputs` orchestration, `applyTemplate`, `resolveTemplateNames` (with warnings), `printTemplateSummary`, `pickTemplate`

internal/verda-cli/cmd/vm/create.go

@@ -103,6 +103,7 @@ func NewCmdCreate(f cmdutil.Factory, ioStreams cmdutil.IOStreams) *cobra.Command
 		Long: cmdutil.LongDesc(`
 			Create a Verda VM instance. Without flags, launches an interactive
 			wizard. Use --from to pre-fill settings from a saved template.
+			Flags passed alongside --from override the template values.
 
 			Templates are created with "verda template create" and stored
 			as YAML files under ~/.verda/templates/vm/.
@@ -121,6 +122,10 @@ func NewCmdCreate(f cmdutil.Factory, ioStreams cmdutil.IOStreams) *cobra.Command
 			# From a template file
 			verda vm create --from ./my-template.yaml
 
+			# From a template, override specific fields with flags
+			verda vm create --from gpu-training --location FIN-03
+			verda vm create --from gpu-training --hostname my-vm --os-volume-size 200
+
 			# Non-interactive with all flags
 			verda vm create \
 			  --kind gpu \

internal/verda-cli/cmd/vm/template_apply.go

@@ -32,7 +32,10 @@ func resolveCreateInputs(
 	}
 
 	// Run wizard for any remaining missing fields.
-	if opts.InstanceType == "" || opts.Image == "" || opts.Hostname == "" {
+	// When a template was used but didn't specify a location, prompt the user
+	// so they can pick where to deploy instead of silently defaulting to FIN-01.
+	templateWithoutLocation := cmd.Flags().Changed("from") && !opts.locationSet
+	if opts.InstanceType == "" || opts.Image == "" || opts.Hostname == "" || templateWithoutLocation {
 		if err := runWizard(cmd.Context(), f, ioStreams, opts); err != nil {
 			return true, err
 		}