feat(ui): UX polish -- hints, required markers, actionable errors

- Tab-specific empty state hints guide new users (closes #232)
- Undo hint shown after edits: "Saved. u to undo" (closes #233)
- Required field markers with " *" suffix on all mandatory inputs (closes #235)
- Onboarding nudge after first house setup with keybinding tips
- Actionable LLM error messages: "start it with `ollama serve`",
  "pull it with `ollama pull <model>`" (closes #221, closes #222)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cpcloud

internal/app/forms.go

@@ -122,7 +122,7 @@ func (m *Model) startHouseForm() {
 	form := huh.NewForm(
 		huh.NewGroup(
 			huh.NewInput().
-				Title("Nickname").
+				Title("Nickname *").
 				Description("Ex: Primary Residence").
 				Value(&values.Nickname).
 				Validate(requiredText("nickname")),
@@ -210,7 +210,7 @@ func (m *Model) startProjectForm() {
 	form := huh.NewForm(
 		huh.NewGroup(
 			huh.NewInput().
-				Title("Title").
+				Title("Title *").
 				Value(&values.Title).
 				Validate(requiredText("title")),
 			huh.NewSelect[uint]().
@@ -242,7 +242,7 @@ func (m *Model) openProjectForm(values *projectFormData, options []huh.Option[ui
 	form := huh.NewForm(
 		huh.NewGroup(
 			huh.NewInput().
-				Title("Title").
+				Title("Title *").
 				Value(&values.Title).
 				Validate(requiredText("title")),
 			huh.NewSelect[uint]().
@@ -299,11 +299,11 @@ func (m *Model) startQuoteForm() error {
 				Options(options...).
 				Value(&values.ProjectID),
 			huh.NewInput().
-				Title("Vendor name").
+				Title("Vendor name *").
 				Value(&values.VendorName).
 				Validate(requiredText("vendor name")),
 			huh.NewInput().
-				Title("Total").
+				Title("Total *").
 				Placeholder("3250.00").
 				Value(&values.Total).
 				Validate(requiredMoney("total")),
@@ -340,7 +340,7 @@ func (m *Model) openQuoteForm(values *quoteFormData, projectOpts []huh.Option[ui
 				Options(projectOpts...).
 				Value(&values.ProjectID),
 			huh.NewInput().
-				Title("Vendor name").
+				Title("Vendor name *").
 				Value(&values.VendorName).
 				Validate(requiredText("vendor name")),
 			huh.NewInput().Title("Contact name").Value(&values.ContactName),
@@ -350,7 +350,7 @@ func (m *Model) openQuoteForm(values *quoteFormData, projectOpts []huh.Option[ui
 		).Title("Vendor"),
 		huh.NewGroup(
 			huh.NewInput().
-				Title("Total").
+				Title("Total *").
 				Placeholder("3250.00").
 				Value(&values.Total).
 				Validate(requiredMoney("total")),
@@ -390,7 +390,7 @@ func (m *Model) startMaintenanceForm() {
 	form := huh.NewForm(
 		huh.NewGroup(
 			huh.NewInput().
-				Title("Item").
+				Title("Item *").
 				Value(&values.Name).
 				Validate(requiredText("item")),
 			huh.NewSelect[uint]().
@@ -433,7 +433,7 @@ func (m *Model) openMaintenanceForm(
 	form := huh.NewForm(
 		huh.NewGroup(
 			huh.NewInput().
-				Title("Item").
+				Title("Item *").
 				Value(&values.Name).
 				Validate(requiredText("item")),
 			huh.NewSelect[uint]().
@@ -473,7 +473,7 @@ func (m *Model) startApplianceForm() {
 	form := huh.NewForm(
 		huh.NewGroup(
 			huh.NewInput().
-				Title("Name").
+				Title("Name *").
 				Placeholder("Kitchen Refrigerator").
 				Value(&values.Name).
 				Validate(requiredText("name")),
@@ -497,7 +497,7 @@ func (m *Model) openApplianceForm(values *applianceFormData) {
 	form := huh.NewForm(
 		huh.NewGroup(
 			huh.NewInput().
-				Title("Name").
+				Title("Name *").
 				Placeholder("Kitchen Refrigerator").
 				Value(&values.Name).
 				Validate(requiredText("name")),
@@ -573,7 +573,7 @@ func (m *Model) startVendorForm() {
 	form := huh.NewForm(
 		huh.NewGroup(
 			huh.NewInput().
-				Title("Name").
+				Title("Name *").
 				Placeholder("Acme Plumbing").
 				Value(&values.Name).
 				Validate(requiredText("name")),
@@ -597,7 +597,7 @@ func (m *Model) openVendorForm(values *vendorFormData) {
 	form := huh.NewForm(
 		huh.NewGroup(
 			huh.NewInput().
-				Title("Name").
+				Title("Name *").
 				Placeholder("Acme Plumbing").
 				Value(&values.Name).
 				Validate(requiredText("name")),
@@ -908,7 +908,7 @@ func (m *Model) startServiceLogForm(maintenanceItemID uint) error {
 	form := huh.NewForm(
 		huh.NewGroup(
 			huh.NewInput().
-				Title("Date serviced (YYYY-MM-DD)").
+				Title("Date serviced * (YYYY-MM-DD)").
 				Value(&values.ServicedAt).
 				Validate(requiredDate("date serviced")),
 			huh.NewSelect[uint]().
@@ -940,7 +940,7 @@ func (m *Model) openServiceLogForm(
 	form := huh.NewForm(
 		huh.NewGroup(
 			huh.NewInput().
-				Title("Date serviced (YYYY-MM-DD)").
+				Title("Date serviced * (YYYY-MM-DD)").
 				Value(&values.ServicedAt).
 				Validate(requiredDate("date serviced")),
 			huh.NewSelect[uint]().
@@ -1106,7 +1106,7 @@ func (m *Model) openDatePicker(
 		if err := m.handleFormSubmit(); err != nil {
 			m.setStatusError(err.Error())
 		} else {
-			m.setStatusInfo("Saved.")
+			m.setStatusSaved(true) // calendar inline edits are always edits
 			m.reloadAfterFormSave(savedKind)
 		}
 		m.formKind = formNone

internal/app/model.go

@@ -1300,6 +1300,8 @@ func (m *Model) statusLines() int {
 }
 
 func (m *Model) saveForm() tea.Cmd {
+	wasEdit := m.editID != nil
+	isFirstHouse := m.formKind == formHouse && !m.hasHouse
 	m.snapshotForUndo()
 	kind := m.formKind
 	err := m.handleFormSubmit()
@@ -1308,7 +1310,11 @@ func (m *Model) saveForm() tea.Cmd {
 		return nil
 	}
 	m.exitForm()
-	m.setStatusInfo("Saved.")
+	if isFirstHouse {
+		m.setStatusInfo("House set up. b/f to switch tabs, i to edit, ? for help")
+	} else {
+		m.setStatusSaved(wasEdit)
+	}
 	m.reloadAfterFormSave(kind)
 	return nil
 }
@@ -1408,7 +1414,7 @@ func (m *Model) submitInlineInput() {
 		return
 	}
 	m.closeInlineInput()
-	m.setStatusInfo("Saved.")
+	m.setStatusSaved(true) // inline edits are always edits
 	m.reloadAfterFormSave(kind)
 }
 
@@ -1439,6 +1445,16 @@ func (m *Model) setStatusInfo(text string) {
 	m.status = statusMsg{Text: text, Kind: statusInfo}
 }
 
+// setStatusSaved sets a "Saved." status message, appending an undo hint
+// when the save was an edit (not a create).
+func (m *Model) setStatusSaved(wasEdit bool) {
+	if wasEdit && len(m.undoStack) > 0 {
+		m.setStatusInfo("Saved. u to undo")
+	} else {
+		m.setStatusInfo("Saved.")
+	}
+}
+
 func (m *Model) setStatusError(text string) {
 	m.status = statusMsg{Text: text, Kind: statusError}
 }

internal/app/view.go

@@ -900,7 +900,7 @@ func (m *Model) tableView(tab *Tab) string {
 		if tab.FilterActive && hasPins(tab) {
 			bodyParts = append(bodyParts, m.styles.Empty.Render("No matches."))
 		} else {
-			bodyParts = append(bodyParts, m.styles.Empty.Render("No entries yet."))
+			bodyParts = append(bodyParts, m.styles.Empty.Render(emptyHint(tab.Kind)))
 		}
 	} else {
 		bodyParts = append(bodyParts, strings.Join(rows, "\n"))
@@ -1074,6 +1074,24 @@ func truncateLeft(s string, maxW int) string {
 	return ansi.TruncateLeft(s, sw-maxW+1, "…")
 }
 
+// emptyHint returns a context-aware empty state message for the given tab.
+func emptyHint(kind TabKind) string {
+	switch kind {
+	case tabProjects:
+		return "No projects yet. Press i then a to add one."
+	case tabQuotes:
+		return "No quotes yet. Add a project first, then press i then a."
+	case tabMaintenance:
+		return "No maintenance items yet. Press i then a to add one."
+	case tabAppliances:
+		return "No appliances yet. Press i then a to add one."
+	case tabVendors:
+		return "No vendors yet. Press i then a to add one."
+	default:
+		return "No entries yet."
+	}
+}
+
 // wordWrap breaks text into lines of at most maxW visible columns, splitting
 // on word boundaries when possible.
 func wordWrap(text string, maxW int) string {

internal/app/view_test.go

@@ -729,3 +729,35 @@ func TestDeletedHintProminentWhenShowDeleted(t *testing.T) {
 	status := m.statusView()
 	assert.Contains(t, status, "deleted")
 }
+
+func TestEmptyHintPerTab(t *testing.T) {
+	tests := []struct {
+		kind TabKind
+		want string
+	}{
+		{tabProjects, "No projects yet"},
+		{tabQuotes, "No quotes yet"},
+		{tabMaintenance, "No maintenance items yet"},
+		{tabAppliances, "No appliances yet"},
+		{tabVendors, "No vendors yet"},
+	}
+	for _, tt := range tests {
+		hint := emptyHint(tt.kind)
+		assert.Contains(t, hint, tt.want)
+		assert.Contains(t, hint, "i then a", "should contain add instruction")
+	}
+}
+
+func TestSetStatusSavedWithUndo(t *testing.T) {
+	m := newTestModel()
+	m.undoStack = append(m.undoStack, undoEntry{Description: "test"})
+	m.setStatusSaved(true)
+	assert.Contains(t, m.status.Text, "u to undo")
+}
+
+func TestSetStatusSavedNoUndo(t *testing.T) {
+	m := newTestModel()
+	m.setStatusSaved(false)
+	assert.Equal(t, "Saved.", m.status.Text)
+	assert.NotContains(t, m.status.Text, "undo")
+}

internal/llm/client.go

@@ -112,7 +112,7 @@ func (c *Client) ListModels(ctx context.Context) ([]string, error) {
 	resp, err := c.http.Do(req)
 	if err != nil {
 		return nil, fmt.Errorf(
-			"cannot reach %s -- is the inference server running?",
+			"cannot reach %s -- start it with `ollama serve`",
 			c.baseURL,
 		)
 	}
@@ -197,7 +197,7 @@ func (c *Client) PullModel(ctx context.Context, model string) (*PullScanner, err
 	resp, err := c.http.Do(req)
 	if err != nil {
 		return nil, fmt.Errorf(
-			"cannot reach %s -- is the inference server running?",
+			"cannot reach %s -- start it with `ollama serve`",
 			ollamaBase,
 		)
 	}
@@ -229,7 +229,7 @@ func (c *Client) Ping(ctx context.Context) error {
 	resp, err := c.http.Do(req)
 	if err != nil {
 		return fmt.Errorf(
-			"cannot reach %s -- is the inference server running?",
+			"cannot reach %s -- start it with `ollama serve`",
 			c.baseURL,
 		)
 	}
@@ -252,8 +252,8 @@ func (c *Client) Ping(ctx context.Context) error {
 		}
 	}
 	return fmt.Errorf(
-		"model %q not found at %s -- is it pulled/loaded?",
-		c.model, c.baseURL,
+		"model %q not found -- pull it with `ollama pull %s`",
+		c.model, c.model,
 	)
 }
 
@@ -288,7 +288,7 @@ func (c *Client) ChatComplete(
 	resp, err := c.http.Do(req)
 	if err != nil {
 		return "", fmt.Errorf(
-			"cannot reach %s -- is the inference server running?",
+			"cannot reach %s -- start it with `ollama serve`",
 			c.baseURL,
 		)
 	}
@@ -340,7 +340,7 @@ func (c *Client) ChatStream(
 	resp, err := c.http.Do(req)
 	if err != nil {
 		return nil, fmt.Errorf(
-			"cannot reach %s -- is the inference server running?",
+			"cannot reach %s -- start it with `ollama serve`",
 			c.baseURL,
 		)
 	}

internal/llm/client_test.go

@@ -36,13 +36,15 @@ func TestPingModelNotFound(t *testing.T) {
 	err := client.Ping(context.Background())
 	assert.Error(t, err)
 	assert.Contains(t, err.Error(), "not found")
+	assert.Contains(t, err.Error(), "ollama pull", "should include actionable remediation")
 }
 
 func TestPingServerDown(t *testing.T) {
 	client := NewClient("http://127.0.0.1:1", "qwen3")
 	err := client.Ping(context.Background())
 	assert.Error(t, err)
 	assert.Contains(t, err.Error(), "cannot reach")
+	assert.Contains(t, err.Error(), "ollama serve", "should include actionable remediation")
 }
 
 func TestChatStreamSuccess(t *testing.T) {