diff --git a/.opencode/command/define-design.md b/.opencode/command/define-design.md
index 05288a5..eea903d 100644
--- a/.opencode/command/define-design.md
+++ b/.opencode/command/define-design.md
@@ -171,6 +171,7 @@ Design documents created:
 
 Next steps:
 - Review docs/design/ (especially ui-blueprint.json)
+- Refine the design with /update-design <change> (or re-run /define-design) until approved — do this BEFORE generating code
 - Run /generate-app web | flutter | winui3 to generate the initial app
 - Use /update-design when a feature changes the UI
 - Use /add-feature to add features (it respects the design spec)
diff --git a/.opencode/command/generate-app.md b/.opencode/command/generate-app.md
index a30b24b..884e610 100644
--- a/.opencode/command/generate-app.md
+++ b/.opencode/command/generate-app.md
@@ -40,6 +40,7 @@ opencode
    - `docs/design/ui-blueprint.json`
    - `docs/design/platform-mapping.md`
 3. **Important**: Do **not** generate any platform-specific implementation before this command is executed. This command is the only place initial app scaffolding is created.
+4. This command generates from the design **as-is**. Refine the design first (re-run `/define-design` or use `/update-design <change>`) if anything needs to change — it is far easier to refine before code is generated than after.
 
 ## Procedure
 
diff --git a/.opencode/command/update-design.md b/.opencode/command/update-design.md
index c66a049..8bd24e9 100644
--- a/.opencode/command/update-design.md
+++ b/.opencode/command/update-design.md
@@ -1,11 +1,11 @@
 ---
-description: Update the design spec when a feature request changes the UI (blueprint first, then tokens, brief, and SVGs)
+description: Refine the design before /generate-app, or update it when a feature changes the UI (blueprint first, then tokens, brief, and SVGs)
 agent: build
 ---
 
 # Update Design
 
-This command updates the design specification when a feature request changes the UI. It updates the structured design files **only** — it does **not** implement application code unless explicitly requested.
+This command updates the design specification. It is used in two situations: (1) to refine the UI/UX **before** running `/generate-app` (e.g. adjusting screens, tokens, or layout after reviewing the initial design), and (2) to update the design when a feature changes the UI. It updates the structured design files **only** — it does **not** implement application code unless explicitly requested.
 
 **Change description**: `$ARGUMENTS` (e.g. `/update-design add a profile screen with avatar and edit form`)
 
diff --git a/AGENTS.md b/AGENTS.md
index 8e126eb..367db17 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -107,8 +107,9 @@ Define "what to do this time" for a specific development task:
 1. Use this template
 2. Create persistent documents with `/setup-project` (automatically creating six)
 3. Define the UI/UX design with `/define-design` (creates `docs/design/`)
-4. Generate the initial app with `/generate-app web | flutter | winui3`
-5. Implement features with `/add-feature [feature]`
+4. Review and refine the UI/UX with `/update-design` (or re-run `/define-design`) until approved — before generating code
+5. Generate the initial app with `/generate-app web | flutter | winui3`
+6. Implement features with `/add-feature [feature]`
 
 ### Day-to-Day Usage
 
diff --git a/README.md b/README.md
index 3274d7a..83f1e72 100644
--- a/README.md
+++ b/README.md
@@ -243,6 +243,13 @@ Creates the design specification under `docs/design/` (design brief, design toke
 platform mapping, and SVG wireframes). You'll be asked about target platform, visual style, main
 screens, navigation, branding, and accessibility; if you don't specify, sensible defaults are proposed.
 
+Review and refine the UI/UX **before** generating the app — it is far easier to iterate on the design
+than on generated code:
+
+- Re-run `/define-design` to change the overall direction.
+- Run `/update-design <change>` for targeted refinements (e.g. `/update-design make the home screen denser`).
+- Iterate until the design — especially `docs/design/ui-blueprint.json` — is approved.
+
 **The design source of truth is `docs/design/ui-blueprint.json`.** SVG files are visual references only.
 
 ### 3. Generate the app
@@ -300,7 +307,9 @@ Recommended workflow:
 
 1. Run `/setup-project`
 2. Run `/define-design`
-3. Review `docs/design/`
+3. Review `docs/design/` and refine the UI/UX until approved:
+   - Re-run `/define-design` to change direction, or
+   - Run `/update-design <change>` for targeted refinements
 4. Run `/generate-app web`, `/generate-app flutter`, or `/generate-app winui3`
 5. Use `/add-feature` to add features
 6. Use `/update-design` whenever a feature changes the UI