TW-5364: fix code review findings, add agent lists support and docs links

.gitignore

@@ -194,3 +194,6 @@ playwright-report/
 *phase*.md
 ci-output.txt
 ci-results.txt
+
+# Brainstorming visual companion sessions
+.superpowers/

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build test-unit test-race test-integration test-integration-fast test-cli-regressions test-integration-agent test-cleanup test-coverage test-air test-air-integration test-e2e test-e2e-air test-e2e-ui test-playwright test-playwright-air test-playwright-ui test-playwright-interactive test-playwright-headed clean clean-cache install fmt vet lint vuln deps security check-context ci ci-full help
+.PHONY: build test-unit test-race test-integration test-integration-fast test-cli-regressions test-integration-agent test-cleanup test-coverage test-air test-air-integration test-e2e test-e2e-air test-e2e-ui test-playwright test-playwright-air test-playwright-ui test-playwright-studio test-playwright-interactive test-playwright-headed clean clean-cache install fmt vet lint vuln deps security check-context ci ci-full help
 
 # Disable parallel Make execution - prevents Go build cache corruption on btrfs (CachyOS)
 .NOTPARALLEL:
@@ -237,6 +237,19 @@ test-cleanup:
 		fi \
 	done
 	@echo ""
+	@echo "4. Cleaning test agent lists..."
+	@./bin/nylas agent list list 2>/dev/null | \
+		grep -A1 "^it-rule-matrix-" | \
+		grep "ID:" | \
+		awk '{print $$2}' | \
+		while read list_id; do \
+			if [ ! -z "$$list_id" ]; then \
+				echo "  Deleting test list: $$list_id"; \
+				./bin/nylas agent list delete $$list_id --yes 2>/dev/null && \
+				echo "    ✓ Deleted list $$list_id" || echo "    ⚠ Could not delete $$list_id"; \
+			fi \
+		done
+	@echo ""
 	@echo "✓ Test cleanup complete"
 
 # ============================================================================
@@ -299,6 +312,17 @@ test-playwright-ui:
 	@cd tests && UI_E2E_DEMO=true npx playwright test --project=ui-chromium
 	@echo "✓ UI E2E tests complete!"
 
+test-playwright-studio:
+	@echo "=== Running Playwright Agent Studio Tests ==="
+	@command -v npm >/dev/null 2>&1 || { \
+		echo "ERROR: npm not installed"; \
+		exit 1; \
+	}
+	@$(MAKE) --no-print-directory build
+	@cd tests && npm install
+	@cd tests && npx playwright test --project=studio-chromium
+	@echo "✓ Agent Studio E2E tests complete!"
+
 test-playwright-interactive:
 	@echo "=== Running Playwright E2E Tests (Interactive Mode) ==="
 	@$(MAKE) --no-print-directory build

docs/COMMANDS.md

@@ -370,8 +370,13 @@ nylas calendar focus-time list                                   # List focus ti
 **Timezone features:**
 ```bash
 nylas calendar events list --timezone America/Los_Angeles --show-tz
+nylas calendar events create --title T --start "2026-06-15 14:00" \
+  --timezone America/New_York --lock-timezone   # Create in a specific zone and lock it
+nylas calendar events update <event-id> --unlock-timezone
 ```
 
+Event times are parsed in your system timezone unless `--timezone` is set; the zone is recorded on the event. `--lock-timezone` pins the event to that zone in list/show views. All-day events (`--all-day`) take a date only (`YYYY-MM-DD`) — a time component is an error.
+
 **AI scheduling:**
 ```bash
 nylas calendar schedule ai "meeting with John next Tuesday afternoon"
@@ -463,6 +468,7 @@ nylas agent account create <email>             # Create agent account
 nylas agent account create <email> --app-password PW  # Create account with IMAP/SMTP app password
 nylas agent account update [agent-id|email] --app-password PW  # Add or rotate IMAP/SMTP app password
 nylas agent account get <agent-id|email>       # Show one agent account
+nylas agent account move <agent-id|email> --workspace <id>  # Move account to another workspace
 nylas agent account delete <agent-id|email>    # Delete/revoke agent account
 nylas agent account delete <agent-id|email> --yes  # Skip confirmation
 nylas agent policy list                        # List all policies
@@ -479,10 +485,25 @@ nylas agent rule create --name NAME --trigger outbound --condition recipient.dom
 nylas agent rule create --data-file rule.json  # Create a rule from full JSON
 nylas agent rule update <rule-id> --name NAME --description TEXT  # Update a rule
 nylas agent rule delete <rule-id> --yes        # Delete a rule
+nylas agent list list                          # List all lists
+nylas agent list get <list-id>                 # Show one list and its items
+nylas agent list create --name NAME --type domain  # Create a list (type: domain, tld, or address)
+nylas agent list create --name NAME --type address --item ceo@example.com  # Create and seed items
+nylas agent list update <list-id> --name NAME  # Update a list's metadata
+nylas agent list items <list-id>               # Show list items
+nylas agent list add <list-id> <item>...       # Add items to a list
+nylas agent list remove <list-id> <item>...    # Remove items from a list
+nylas agent list delete <list-id> --yes        # Delete a list
+nylas agent overview                           # Tree of accounts → workspace → policy/rules → lists
+nylas agent studio                             # Visual management UI (drag-drop board, localhost:7368)
 nylas agent status                             # Check connector + account status
 ```
 
-**Details:** `docs/commands/agent.md`, `docs/commands/agent-policy.md`, `docs/commands/agent-rule.md`
+Lists hold normalized values referenced by rule `in_list` conditions, e.g.
+`--condition from.domain,in_list,<list-id>`. A list's type is immutable and
+determines which rule fields it can match.
+
+**Details:** `docs/commands/agent-getting-started.md` (start here), `docs/commands/agent.md`, `docs/commands/agent-policy.md`, `docs/commands/agent-rule.md`, `docs/commands/agent-list.md`
 
 ---
 

docs/INDEX.md

@@ -73,7 +73,7 @@ Quick navigation guide to find the right documentation for your needs.
 - **Calendar** → [commands/calendar.md](commands/calendar.md)
 - **Contacts** → [commands/contacts.md](commands/contacts.md)
 - **Webhooks** → [commands/webhooks.md](commands/webhooks.md)
-- **Agent accounts** → [commands/agent.md](commands/agent.md)
+- **Agent accounts** → [commands/agent-getting-started.md](commands/agent-getting-started.md) (guide), [commands/agent.md](commands/agent.md) (reference), [commands/agent-studio.md](commands/agent-studio.md) (visual UI)
 - **Scheduler** → [commands/scheduler.md](commands/scheduler.md)
 - **Admin** → [commands/admin.md](commands/admin.md)
 - **Timezone** → [commands/timezone.md](commands/timezone.md)