@@ -152,7 +152,7 @@ func assignItems(cmd *cobra.Command, args []string, assignee *string, project st
 	}
 
 	var results []*assignResult
-	var failed []string
+	var failed, failures []string
 	var firstErr error
 	var assigneeResolved bool
 	var assigneeID string
@@ -167,6 +167,7 @@ func assignItems(cmd *cobra.Command, args []string, assignee *string, project st
 				return fatal.err
 			}
 			failed = append(failed, itemID)
+			failures = append(failures, fmt.Sprintf("%s: %s", itemID, err))
 			if firstErr == nil {
 				firstErr = err
 			}
@@ -206,22 +207,26 @@ func assignItems(cmd *cobra.Command, args []string, assignee *string, project st
 		Description: "Remove assignee",
 	}}
 
+	respOpts := []output.ResponseOption{
+		output.WithSummary(summary),
+		output.WithBreadcrumbs(batchBreadcrumbs...),
+	}
+	// --agent and --quiet print only the data, so the failures would
+	// otherwise be invisible there: a dropped assignee among them.
+	if len(failures) > 0 {
+		respOpts = append(respOpts, output.WithDiagnostic("Not assigned: "+strings.Join(failures, "; ")))
+	}
+
 	if len(results) == 1 {
-		return app.OK(results[0].item,
-			output.WithSummary(summary),
-			output.WithBreadcrumbs(batchBreadcrumbs...),
-		)
+		return app.OK(results[0].item, respOpts...)
 	}
 
 	items := make([]any, len(results))
 	for i, r := range results {
 		items[i] = r.item
 	}
 
-	return app.OK(items,
-		output.WithSummary(summary),
-		output.WithBreadcrumbs(batchBreadcrumbs...),
-	)
+	return app.OK(items, respOpts...)
 }
 
 func unassignItems(cmd *cobra.Command, args []string, assignee *string, project string, isCard, isStep bool) error {
@@ -564,6 +569,9 @@ func doAssignTodo(cmd *cobra.Command, app *appctx.App, todoIDStr, assigneeID str
 	if err != nil {
 		return nil, convertSDKError(err)
 	}
+	if err := checkAssigneesSaved(assigneeTodo, updated.ID, assigneeIDs, updated.Assignees); err != nil {
+		return nil, err
+	}
 
 	assigneeName := findAssigneeName(updated.Assignees, assigneeIDInt)
 
@@ -610,6 +618,9 @@ func doAssignCard(cmd *cobra.Command, app *appctx.App, cardIDStr, assigneeID str
 	if err != nil {
 		return nil, convertSDKError(err)
 	}
+	if err := checkAssigneesSaved(assigneeCard, updated.ID, assigneeIDs, updated.Assignees); err != nil {
+		return nil, err
+	}
 
 	assigneeName := findAssigneeName(updated.Assignees, assigneeIDInt)
 
@@ -656,6 +667,9 @@ func doAssignStep(cmd *cobra.Command, app *appctx.App, stepIDStr, assigneeID str
 	if err != nil {
 		return nil, convertSDKError(err)
 	}
+	if err := checkAssigneesSaved(assigneeCardStep, updated.ID, assigneeIDs, updated.Assignees); err != nil {
+		return nil, err
+	}
 
 	assigneeName := findAssigneeName(updated.Assignees, assigneeIDInt)
 
@@ -782,6 +796,62 @@ func existingAssigneeIDs(people []basecamp.Person) []int64 {
 	return ids
 }
 
+// assigneeRecord is a kind of record that takes assignees, with the command
+// that assigns someone to one that already exists. assignHint is formatted
+// with the record's ID and the people to name; when the command replaces the
+// whole set, those people include the assignees the record kept.
+type assigneeRecord struct {
+	noun       string
+	assignHint string
+	replaces   bool
+}
+
+var (
+	assigneeTodo     = assigneeRecord{noun: "to-do", assignHint: "basecamp assign %d --to %s --project <project>"}
+	assigneeCard     = assigneeRecord{noun: "card", assignHint: "basecamp assign %d --card --to %s --project <project>"}
+	assigneeCardStep = assigneeRecord{noun: "card step", assignHint: "basecamp assign %d --step --to %s --project <project>"}
+	assigneeSubtask  = assigneeRecord{noun: "subtask", assignHint: "basecamp subtasks update %d --assignees %s", replaces: true}
+)
+
+// checkAssigneesSaved fails when the saved record lacks a requested assignee.
+// Basecamp does not reject an assignee ID it cannot assign there (a column ID,
+// a person outside the project): it drops it and saves the rest. The record
+// exists by then, so the error names it and what it was saved with, and the
+// hint fixes that record rather than inviting a second create.
+func checkAssigneesSaved(kind assigneeRecord, id int64, requested []int64, saved []basecamp.Person) error {
+	savedIDs := existingAssigneeIDs(saved)
+	var dropped []string
+	for _, want := range requested {
+		if !containsID(savedIDs, want) {
+			dropped = append(dropped, strconv.FormatInt(want, 10))
+		}
+	}
+	if len(dropped) == 0 {
+		return nil
+	}
+
+	people := "<person>"
+	if kind.replaces {
+		for i := len(savedIDs) - 1; i >= 0; i-- {
+			people = strconv.FormatInt(savedIDs[i], 10) + "," + people
+		}
+	}
+
+	state := "it has no assignees"
+	if len(saved) > 0 {
+		names := make([]string, len(saved))
+		for i, p := range saved {
+			names[i] = p.Name
+		}
+		state = "its assignees are " + strings.Join(names, ", ")
+	}
+	return output.ErrUsageHint(
+		fmt.Sprintf("%s #%d was saved, but Basecamp did not assign %s: not a person who can be assigned there; %s",
+			kind.noun, id, strings.Join(dropped, ", "), state),
+		fmt.Sprintf("Assign it with "+kind.assignHint+", naming someone from basecamp people list --project <project>", id, people),
+	)
+}
+
 // containsID checks if a slice contains a given ID.
 func containsID(ids []int64, target int64) bool {
 	for _, id := range ids {
 
@@ -756,7 +756,18 @@ func (m *mockStepAssignTransport) RoundTrip(req *http.Request) (*http.Response,
 		if err := req.Body.Close(); err != nil {
 			return nil, err
 		}
-		return &http.Response{StatusCode: 200, Body: io.NopCloser(strings.NewReader(stepJSON)), Header: header}, nil
+		var put struct {
+			AssigneeIDs []int64 `json:"assignee_ids"`
+		}
+		if err := json.Unmarshal(body, &put); err != nil {
+			return nil, err
+		}
+		assignees := make([]string, len(put.AssigneeIDs))
+		for i, id := range put.AssigneeIDs {
+			assignees[i] = fmt.Sprintf(`{"id": %d, "name": "Person %d"}`, id, id)
+		}
+		saved := fmt.Sprintf(`{"id": 456, "title": "Existing step", "assignees": [%s]}`, strings.Join(assignees, ","))
+		return &http.Response{StatusCode: 200, Body: io.NopCloser(strings.NewReader(saved)), Header: header}, nil
 	default:
 		return nil, fmt.Errorf("unexpected request method: %s", req.Method)
 	}
 
@@ -0,0 +1,168 @@
+package commands
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"regexp"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/basecamp/basecamp-sdk/go/pkg/basecamp"
+
+	"github.com/basecamp/basecamp-cli/internal/output"
+)
+
+// assigneeEchoTransport plays Basecamp for every command that sets assignees.
+// A record takes its ID from the request path, #999 when the path has none. A
+// write answers with the assignee_ids it was sent, or, when drop matches the
+// path, with none of them: what Basecamp does with an ID it cannot assign,
+// such as a card column's.
+type assigneeEchoTransport struct {
+	drop func(path string) bool
+}
+
+var trailingRecordID = regexp.MustCompile(`/(\d+)(\.json)?$`)
+
+func recordJSON(path, assignees string) string {
+	id := "999"
+	if m := trailingRecordID.FindStringSubmatch(path); m != nil {
+		id = m[1]
+	}
+	return `{"id": ` + id + `, "title": "Thing", "content": "Thing", "assignees": [` + assignees + `]}`
+}
+
+func dropAll(string) bool { return true }
+
+func (m *assigneeEchoTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	header := http.Header{"Content-Type": []string{"application/json"}}
+	respond := func(status int, body string) (*http.Response, error) {
+		return &http.Response{StatusCode: status, Body: io.NopCloser(strings.NewReader(body)), Header: header}, nil
+	}
+
+	path := req.URL.Path
+	switch req.Method {
+	case http.MethodGet:
+		switch {
+		case strings.HasSuffix(path, "/projects.json"):
+			return respond(200, `[{"id": 123, "name": "Test Project"}]`)
+		case strings.HasSuffix(path, "/projects/123.json"):
+			return respond(200, `{"id": 123, "dock": [{"name": "kanban_board", "id": 789, "title": "Card Table"}]}`)
+		case strings.HasSuffix(path, "/people.json"):
+			return respond(200, `[{"id": 42, "name": "Annie Bryan"}]`)
+		}
+		return respond(200, recordJSON(path, ""))
+	case http.MethodPost, http.MethodPut:
+		var body struct {
+			AssigneeIDs []int64 `json:"assignee_ids"`
+		}
+		if err := json.NewDecoder(req.Body).Decode(&body); err != nil {
+			return nil, err
+		}
+		assignees := []string{}
+		if m.drop == nil || !m.drop(path) {
+			for _, id := range body.AssigneeIDs {
+				assignees = append(assignees, fmt.Sprintf(`{"id": %d, "name": "Person %d"}`, id, id))
+			}
+		}
+		status := http.StatusOK
+		if req.Method == http.MethodPost {
+			status = http.StatusCreated
+		}
+		return respond(status, recordJSON(path, strings.Join(assignees, ",")))
+	}
+	return nil, fmt.Errorf("unexpected %s %s", req.Method, path)
+}
+
+type assigneeWrite struct {
+	name string
+	cmd  func() *cobra.Command
+	args []string
+}
+
+// Every command that sets assignees, given the ID of a card column.
+var assigneeWrites = []assigneeWrite{
+	{"cards create --to", NewCardsCmd, []string{"create", "Thing", "--column", "111", "--to", "822400739"}},
+	{"cards update", NewCardsCmd, []string{"update", "999", "--assignee", "822400739"}},
+	{"cards step create", NewCardsCmd, []string{"step", "create", "Thing", "--card", "999", "--assignees", "822400739"}},
+	{"cards step update", NewCardsCmd, []string{"step", "update", "999", "--assignees", "822400739"}},
+	{"todos create", NewTodosCmd, []string{"create", "Thing", "--list", "555", "--assignee", "822400739"}},
+	{"todos update", NewTodosCmd, []string{"update", "999", "--assignee", "822400739"}},
+	{"subtasks create", NewSubtasksCmd, []string{"create", "999", "Thing", "--assignees", "822400739"}},
+	{"subtasks update", NewSubtasksCmd, []string{"update", "999", "--assignees", "822400739"}},
+	{"assign", NewAssignCmd, []string{"999", "--to", "822400739"}},
+	{"assign --card", NewAssignCmd, []string{"999", "--card", "--to", "822400739"}},
+	{"assign --step", NewAssignCmd, []string{"999", "--step", "--to", "822400739"}},
+}
+
+func TestAssigneeWritesFailWhenBasecampDropsTheAssignee(t *testing.T) {
+	for _, w := range assigneeWrites {
+		t.Run(w.name, func(t *testing.T) {
+			app := setupCardsMockApp(t, &assigneeEchoTransport{drop: dropAll})
+
+			err := executeCommand(w.cmd(), app, w.args...)
+
+			var e *output.Error
+			require.True(t, errors.As(err, &e), "want an output error, got %v", err)
+			assert.Equal(t, output.CodeUsage, e.Code)
+			assert.Contains(t, e.Message, "#999")
+			assert.Contains(t, e.Message, "822400739")
+		})
+	}
+}
+
+func TestAssigneeWritesSucceedWhenBasecampKeepsTheAssignee(t *testing.T) {
+	for _, w := range assigneeWrites {
+		t.Run(w.name, func(t *testing.T) {
+			app := setupCardsMockApp(t, &assigneeEchoTransport{})
+
+			require.NoError(t, executeCommand(w.cmd(), app, w.args...))
+		})
+	}
+}
+
+// A batch that assigns some items still exits 0, so under --agent, which
+// prints only the data, the item Basecamp dropped the person from has to be
+// named on stderr.
+func TestAssignBatchNamesTheItemThatDroppedTheAssignee(t *testing.T) {
+	transport := &assigneeEchoTransport{drop: func(path string) bool { return strings.Contains(path, "/222") }}
+	app := setupCardsMockApp(t, transport)
+	var stdout, stderr bytes.Buffer
+	app.Output = output.New(output.Options{Format: output.FormatQuiet, Writer: &stdout, ErrWriter: &stderr})
+
+	require.NoError(t, executeCommand(NewAssignCmd(), app, "111", "222", "--to", "822400739"))
+
+	assert.Contains(t, stdout.String(), "111")
+	assert.Contains(t, stderr.String(), "notice: Not assigned: 222: to-do #222 was saved, but Basecamp did not assign 822400739")
+}
+
+// Following the hint must not undo what was saved: subtasks update replaces
+// the whole set, so its hint carries the kept assignees, and assign needs the
+// project.
+func TestCheckAssigneesSavedHintKeepsWhatWasSaved(t *testing.T) {
+	kept := []basecamp.Person{{ID: 7, Name: "Ann"}, {ID: 8, Name: "Bo"}}
+
+	var e *output.Error
+	require.True(t, errors.As(checkAssigneesSaved(assigneeSubtask, 5, []int64{7, 8, 9}, kept), &e))
+	assert.Contains(t, e.Hint, "basecamp subtasks update 5 --assignees 7,8,<person>")
+
+	require.True(t, errors.As(checkAssigneesSaved(assigneeCard, 5, []int64{7, 8, 9}, kept), &e))
+	assert.Contains(t, e.Hint, "basecamp assign 5 --card --to <person> --project <project>")
+}
+
+func TestCheckAssigneesSavedNamesWhatTheRecordKept(t *testing.T) {
+	err := checkAssigneesSaved(assigneeCard, 7, []int64{1, 2, 3}, []basecamp.Person{{ID: 2, Name: "Ann"}})
+
+	var e *output.Error
+	require.True(t, errors.As(err, &e))
+	assert.Contains(t, e.Message, "card #7")
+	assert.Contains(t, e.Message, "1, 3")
+	assert.Contains(t, e.Message, "Ann")
+}
@@ -1095,6 +1095,9 @@ Use - as the body argument to read the body from stdin:
 					}
 					return fmt.Errorf("card %d created but assignment failed: %w", createdCardID, sdkErr)
 				}
+				if err := checkAssigneesSaved(assigneeCard, card.ID, []int64{assigneeID}, card.Assignees); err != nil {
+					return err
+				}
 			}
 
 			// Build breadcrumbs - only include --card-table when known
@@ -1137,8 +1140,8 @@ Use - as the body argument to read the body from stdin:
 	}
 
 	cmd.Flags().StringVarP(&column, "column", "c", "", "Column ID or name (defaults to first column)")
-	cmd.Flags().StringVar(&assignee, "assignee", "", "Assignee ID or name")
-	cmd.Flags().StringVar(&assignee, "to", "", "Assignee (alias for --assignee)")
+	cmd.Flags().StringVar(&assignee, "assignee", "", "Person to assign: ID, name, or email")
+	cmd.Flags().StringVar(&assignee, "to", "", "Person to assign (alias for --assignee); the column is --column")
 	cmd.Flags().StringVarP(&due, "due", "d", "", "Due date (natural language or YYYY-MM-DD)")
 	cmd.Flags().StringArrayVar(&attachFiles, "attach", nil, "Attach file (repeatable)")
 
@@ -1263,6 +1266,9 @@ You can pass either a card ID or a Basecamp URL:
 			if err != nil {
 				return convertSDKError(err)
 			}
+			if err := checkAssigneesSaved(assigneeCard, card.ID, req.AssigneeIDs, card.Assignees); err != nil {
+				return err
+			}
 
 			respOpts := []output.ResponseOption{
 				output.WithSummary(fmt.Sprintf("Updated card #%s", cardIDStr)),
@@ -3077,6 +3083,9 @@ func newCardsStepCreateCmd(project *string) *cobra.Command {
 			if err != nil {
 				return convertSDKError(err)
 			}
+			if err := checkAssigneesSaved(assigneeCardStep, step.ID, req.AssigneeIDs, step.Assignees); err != nil {
+				return err
+			}
 
 			return app.OK(step,
 				output.WithSummary(fmt.Sprintf("Created step: %s", step.Title)),
@@ -3165,6 +3174,9 @@ You can pass either a step ID or a Basecamp URL:
 			if err != nil {
 				return convertSDKError(err)
 			}
+			if err := checkAssigneesSaved(assigneeCardStep, step.ID, req.AssigneeIDs, step.Assignees); err != nil {
+				return err
+			}
 
 			return app.OK(step,
 				output.WithSummary(fmt.Sprintf("Updated step #%s", stepIDStr)),