This directory contains comprehensive documentation for the Attio CLI project, covering API concepts, endpoints, CLI specifications, and implementation plan.

1. Core Concepts - Objects, records, lists, attributes, workspaces, actors, slugs vs IDs
2. Authentication - API keys, OAuth, scopes, environment configuration
3. API Fundamentals - Base URL, rate limiting, pagination, filtering, sorting, error handling

4. Workspaces & Members - Workspace member management
5. Objects & Attributes - Object definitions, attribute management, select/status options

6. Records (Generic) - Generic record operations (list, get, create, update, assert, delete)
7. People Records - People-specific endpoints and attributes
8. Company Records - Company-specific endpoints and attributes
9. Deal Records - Deal-specific endpoints and attributes

10. Lists & Entries - List management, entry operations, assert entries, multiselect handling

11. Notes - Create, read, update, delete notes with markdown support
12. Tasks - Task management, assignment, filtering
13. Meetings - Meeting queries, participant filtering (read-only)

14. CLI Specification - Complete CLI command structure, arguments, options, examples
15. Implementation Plan - Phase-by-phase development plan with test specifications

• people: Individual contacts with emails, phone numbers, social profiles
• companies: Organizations with domains, employee counts, categories
• deals: Sales opportunities with stages, values, owners
• users: Workspace user records
• workspaces: Workspace records

POST /v2/objects/{object}/records
PUT /v2/objects/{object}/records?matching_attribute=email_addresses  # Assert

GET /v2/lists                                    # List all lists
POST /v2/lists/{list}/entries                    # Add record to list
PUT /v2/lists/{list}/entries                     # Assert entry
PATCH /v2/lists/{list}/entries/{entry_id}        # Update (append multiselect)

POST /v2/objects/people/records/query
# Body: {"filter": {"email_addresses": {"$contains": "@example.com"}}}

attio <resource> <action> [arguments] [options]

# Examples:
attio workspace members list
attio record create people --data '{...}'
attio entry list my_list --filter '{...}'
attio note create --parent-object people --parent-record-id abc-123
attio task list --linked-object people --completed false

1. Phase 0: Project setup (TypeScript, testing, dependencies)
2. Phase 1: API client foundation (HTTP client, auth, errors)
3. Phase 2: Type definitions & validation (Zod schemas)
4. Phase 3: Workspace endpoints & CLI
5. Phase 4: Objects & attributes
6. Phase 5: Records (people, companies, deals)
7. Phase 6: Lists & entries
8. Phase 7: Notes
9. Phase 7a: Tasks
10. Phase 7b: Meetings
11. Phase 8: Output formatting & polish
12. Phase 9: Integration testing & documentation
13. Phase 10: Build & distribution

• TypeScript strict mode: No implicit any, strict null checks
• No null/undefined: Use explicit error throwing for missing values
• Runtime validation: Zod schemas for all API responses
• Branded types: UUIDs and slugs have distinct types

• Test-Driven Development: Write tests before implementation
• No premature optimization: Implement minimal working solutions
• Explicit error handling: Clear, user-friendly error messages
• Agent-friendly design: Predictable JSON output, clear exit codes
• Comprehensive help: Every command has examples and documentation