@memnexus-ai/cli 0.1.0

package/docs/prd.md

@@ -0,0 +1,748 @@
+# MemNexus CLI - Product Requirements Document
+
+## Overview
+
+The MemNexus CLI (`mx-cli`) is a command-line interface that provides developers with complete access to all mx-core-api endpoints. It enables developers to interact with the MemNexus platform directly from the terminal, facilitating testing, debugging, automation, and integration workflows.
+
+## Goals
+
+### Primary Goals
+- Provide 1:1 coverage of all mx-core-api REST endpoints
+- Offer an intuitive, well-documented developer experience
+- Enable both interactive and scriptable usage patterns
+- Support authentication and configuration management
+- Maintain type safety and validation consistent with mx-core-api
+
+### Secondary Goals
+- Enable easy integration with CI/CD pipelines
+- Support multiple output formats (JSON, table, human-readable)
+- Provide helpful error messages and validation feedback
+- Allow for offline usage with cached schemas (where applicable)
+
+## Non-Goals
+- GUI or web-based interface
+- Real-time monitoring dashboards
+- Direct database access (all operations go through mx-core-api)
+- Support for deprecated or internal-only endpoints
+
+## Technology Stack
+
+### Language & Runtime
+- **TypeScript** with Node.js 18+
+- Leverages existing mx-core-api schemas and type definitions
+
+### Core Dependencies
+- **@memnexus-ai/contracts** - Official TypeScript SDK and API client for mx-core-api
+  - Provides type-safe API client with all endpoint methods
+  - Auto-generated types from OpenAPI specification
+  - Handles HTTP requests via axios
+  - Includes request/response type definitions
+- **commander.js** - CLI framework for command/subcommand structure
+- **chalk** - Terminal output coloring
+- **ora** - Loading spinners for async operations
+- **cli-table3** - Pretty table formatting for list outputs
+- **inquirer** - Interactive prompts when needed
+- **configstore** - Configuration persistence
+- **dotenv** - Environment variable management
+
+### Development Dependencies
+- **TypeScript** - Type checking and compilation
+- **Jest** - Testing framework
+- **ts-node** - Development execution
+- **eslint** - Code linting
+- **prettier** - Code formatting
+
+## Architecture
+
+### System Architecture
+
+```
+┌─────────────┐
+│   mx-cli    │  (This CLI tool)
+└──────┬──────┘
+       │
+       │ Uses @memnexus-ai/contracts
+       │ (TypeScript SDK)
+       ▼
+┌──────────────────┐
+│  API Gateway     │  (Kong OSS)
+│  (Kong Plugins)  │  - CORS handling
+│                  │  - Rate limiting
+│                  │  - Authentication
+│                  │  - Request logging
+└────────┬─────────┘
+         │
+         │ Proxies to
+         ▼
+┌──────────────────┐
+│   mx-core-api    │  (Express.js REST API)
+│                  │  - Business logic
+│                  │  - Data validation
+└────────┬─────────┘
+         │
+         │ Queries
+         ▼
+┌──────────────────┐
+│     Neo4j        │  (Graph Database)
+│                  │  - Memory storage
+│                  │  - Relationship graphs
+└──────────────────┘
+```
+
+**Default API Endpoints:**
+- **Production**: `https://api.memnexus.io` (via API Gateway)
+- **Staging**: `https://api-staging.memnexus.io` (via API Gateway)
+- **Development**: Configurable via `MX_API_URL` environment variable
+  - Gateway: `http://localhost:8000` (Kong local)
+  - Direct: `http://localhost:3000` (mx-core-api for local dev/testing)
+
+### Project Structure
+```
+mx-cli/
+├── .github/
+│   └── workflows/
+│       └── publish.yml     # GitHub Actions publish workflow
+├── docs/
+│   └── prd.md
+├── src/
+│   ├── commands/           # Command implementations
+│   │   ├── memories.ts
+│   │   ├── conversations.ts
+│   │   ├── topics.ts
+│   │   ├── patterns.ts
+│   │   ├── artifacts.ts
+│   │   ├── facts.ts
+│   │   ├── graphrag.ts
+│   │   ├── apikeys.ts
+│   │   ├── system.ts
+│   │   └── auth.ts
+│   ├── lib/                # Shared utilities
+│   │   ├── api-client.ts   # Wrapper around @memnexus-ai/contracts
+│   │   ├── auth.ts         # Authentication logic
+│   │   ├── config.ts       # Configuration management
+│   │   ├── formatters.ts   # Output formatting (table, JSON, YAML)
+│   │   ├── validators.ts   # Input validation helpers
+│   │   └── errors.ts       # Error handling and display
+│   ├── types/              # TypeScript type definitions
+│   │   └── index.ts
+│   └── index.ts            # CLI entry point
+├── tests/
+│   ├── commands/
+│   └── lib/
+├── package.json
+├── tsconfig.json
+├── .eslintrc.js
+├── .prettierrc
+└── README.md
+```
+
+### Command Structure
+
+The CLI follows a hierarchical command structure:
+
+```
+mx <resource> <action> [options]
+```
+
+Examples:
+```bash
+# List memories
+mx memories list
+
+# Get specific memory
+mx memories get <id>
+
+# Start a conversation first (required for creating memories)
+mx conversations start --user-id <userId>
+
+# Create memory (requires conversationId from previous step)
+mx memories create --content "..." --conversation-id <conversationId>
+
+# Search conversations
+mx conversations search --query "..."
+
+# Merge topics
+mx topics merge --sourceId <id> --targetId <id>
+```
+
+### Configuration Management
+
+#### Config File Location
+- **Linux/macOS**: `~/.config/memnexus/config.json`
+- **Windows**: `%APPDATA%/memnexus/config.json`
+
+#### Config Structure
+```json
+{
+  "apiUrl": "https://api.memnexus.io",
+  "apiKey": "encrypted-api-key",
+  "defaultFormat": "table",
+  "defaultPageSize": 20
+}
+```
+
+#### Environment Variables
+- `MX_API_URL` - API Gateway endpoint override (default: `https://api.memnexus.io`)
+- `MX_API_KEY` - API key override
+- `MX_OUTPUT_FORMAT` - Output format override (json|table|yaml)
+
+#### API Client Integration
+
+The CLI uses `@memnexus-ai/contracts` package for all API interactions:
+
+```typescript
+// src/lib/api-client.ts
+import { CoreApiClient, createClient } from '@memnexus-ai/contracts';
+import { getConfig } from './config';
+
+export function getApiClient(): CoreApiClient {
+  const config = getConfig();
+
+  return createClient({
+    baseURL: config.apiUrl || process.env.MX_API_URL || 'https://api.memnexus.io',
+    apiKey: config.apiKey || process.env.MX_API_KEY,
+    timeout: 30000
+  });
+}
+
+// Usage in commands
+// src/commands/memories.ts
+import { getApiClient } from '../lib/api-client';
+
+export async function listMemories(options: any) {
+  const client = getApiClient();
+  const response = await client.memories.list({
+    limit: options.limit,
+    offset: options.page * options.limit
+  });
+  // Format and display response...
+}
+```
+
+**Benefits:**
+- Type-safe API calls with auto-generated types from OpenAPI spec
+- Consistent error handling across all commands
+- Automatic updates when API changes (via contracts package updates)
+- No need to manually define request/response types
+- Leverages existing, tested API client code
+
+### Authentication
+
+#### API Key Authentication
+1. User generates API key via mx-core-api or customer portal
+2. User configures CLI: `mx auth login --api-key <key>`
+3. CLI encrypts and stores key in config file
+4. All subsequent requests include API key in header: `X-API-Key: <key>`
+
+#### JWT Authentication (Optional/Future)
+- Support for JWT-based authentication for user accounts
+- Token refresh logic
+- Session management
+
+## Feature Requirements
+
+### Core Features
+
+#### 1. Memories Management
+Commands for managing memories:
+- `mx memories list [options]` - List memories with pagination
+  - Options: `--page`, `--limit`, `--conversation-id`, `--format`
+- `mx memories get <id>` - Get specific memory by ID
+- `mx memories create [options]` - Create new memory
+  - **Required**: `--content`, `--conversation-id`
+  - **Optional**: `--tags`, `--metadata`, `--memory-type`, `--role`, `--raw-prompt`
+  - **Note**: Must have a valid conversationId (create with `mx conversations start` first)
+  - Interactive mode if options not provided
+- `mx memories update <id> [options]` - Update memory
+- `mx memories delete <id>` - Delete memory
+- `mx memories search [options]` - Search memories
+  - Options: `--query`, `--mode`, `--conversation-id`, `--limit`
+
+#### 2. Conversations Management
+Commands for conversation operations:
+- `mx conversations start [options]` - **Start a new conversation** (required before creating memories)
+  - **Required**: `--user-id`
+  - **Optional**: `--system-prompt`, `--metadata`
+  - Returns a conversationId for use in memory creation
+- `mx conversations list [options]` - List conversations
+- `mx conversations get <id>` - Get conversation summary
+- `mx conversations timeline <id>` - Get conversation timeline
+- `mx conversations search [options]` - Search conversations
+- `mx conversations by-topic [options]` - Find by topic
+
+#### 3. Topics Management
+Commands for topic operations:
+- `mx topics list [options]` - List topics
+- `mx topics get <id>` - Get topic details
+- `mx topics merge [options]` - Merge topics
+  - Options: `--sourceId`, `--targetId`
+- `mx topics discover-related [options]` - Discover related topics
+- `mx topics similarity [options]` - Calculate topic similarity
+- `mx topics find-similar [options]` - Find similar topics
+- `mx topics cluster [options]` - Cluster topics
+- `mx topics detect-communities [options]` - Detect communities
+
+#### 4. Communities Management
+Commands for community operations:
+- `mx communities list [options]` - List communities
+- `mx communities get <id>` - Get community details
+- `mx communities merge [options]` - Merge communities
+
+#### 5. Patterns Management
+Commands for pattern operations:
+- `mx patterns list [options]` - List patterns
+- `mx patterns compile [options]` - Compile patterns from memories
+- `mx patterns update <id> [options]` - Update pattern
+- `mx patterns feedback [options]` - Record pattern feedback
+- `mx patterns behavior-state` - Get behavioral state
+- `mx patterns set-behavior-state [options]` - Update behavioral state
+
+#### 6. Artifacts Management
+Commands for artifact operations:
+- `mx artifacts list [options]` - List artifacts
+- `mx artifacts get <id>` - Get artifact
+- `mx artifacts create [options]` - Create artifact
+- `mx artifacts update <id> [options]` - Update artifact
+- `mx artifacts delete <id>` - Delete artifact
+
+#### 7. Facts Management
+Commands for semantic facts:
+- `mx facts list [options]` - List facts
+- `mx facts get <id>` - Get fact
+- `mx facts create [options]` - Create fact
+- `mx facts update <id> [options]` - Update fact
+- `mx facts delete <id>` - Delete fact
+- `mx facts search [options]` - Search facts
+
+#### 8. GraphRAG Operations
+Commands for GraphRAG queries:
+- `mx graphrag query [options]` - Execute GraphRAG query
+  - Options: `--query`, `--contextId`, `--mode`
+- `mx graphrag explain <resultId>` - Explain query result
+- `mx graphrag query-communities [options]` - Query communities
+
+#### 9. API Keys Management
+Commands for API key operations:
+- `mx apikeys list` - List API keys
+- `mx apikeys get <id>` - Get API key details
+- `mx apikeys create [options]` - Create new API key
+  - Options: `--name`, `--description`, `--expiresAt`
+- `mx apikeys delete <id>` - Delete API key
+
+#### 10. System Operations
+Commands for system information:
+- `mx system health` - Check system health
+- `mx system status` - Get context status
+- `mx system stats` - Get database statistics
+- `mx system clear-cache` - Clear system cache
+
+#### 11. Authentication & Configuration
+Commands for CLI setup:
+- `mx auth login [options]` - Configure authentication
+  - Options: `--api-key`, `--interactive`
+- `mx auth logout` - Remove stored credentials
+- `mx auth status` - Show current authentication status
+- `mx config set <key> <value>` - Set configuration value
+- `mx config get <key>` - Get configuration value
+- `mx config list` - List all configuration
+- `mx config reset` - Reset to defaults
+
+### Output Formatting
+
+#### Supported Formats
+1. **Table** (default for lists)
+   - Human-readable tabular output
+   - Truncated fields for terminal width
+   - Colored headers and key columns
+
+2. **JSON** (default for single items)
+   - Pretty-printed JSON
+   - Machine-readable
+   - Ideal for scripting
+
+3. **YAML** (optional)
+   - Human-readable structured data
+   - Good for configuration-like outputs
+
+#### Format Selection
+- Global flag: `--format <json|table|yaml>`
+- Config file: `defaultFormat`
+- Environment: `MX_OUTPUT_FORMAT`
+
+### Error Handling
+
+#### Error Types
+1. **Network Errors**
+   - Connection timeout
+   - DNS resolution failure
+   - Certificate errors
+
+2. **API Errors**
+   - 401 Unauthorized - Invalid or missing API key
+   - 403 Forbidden - Insufficient permissions
+   - 404 Not Found - Resource doesn't exist
+   - 422 Validation Error - Invalid input
+   - 429 Rate Limit - Too many requests
+   - 500 Server Error - API internal error
+
+3. **Validation Errors**
+   - Missing required arguments
+   - Invalid argument types
+   - Schema validation failures
+
+4. **Configuration Errors**
+   - Missing config file
+   - Invalid config format
+   - Missing required config values
+
+#### Error Display
+- Clear, actionable error messages
+- Suggestions for resolution
+- Exit codes for scripting:
+  - `0` - Success
+  - `1` - General error
+  - `2` - Validation error
+  - `3` - Authentication error
+  - `4` - Network error
+  - `5` - API error
+
+### User Experience Features
+
+#### Interactive Mode
+For complex commands, provide interactive prompts when required options are missing:
+```bash
+$ mx memories create
+? Enter memory content: This is important information
+? Enter context ID: ctx_123
+? Add tags (comma-separated): important, meeting
+✓ Memory created successfully (mem_456)
+```
+
+#### Progress Indicators
+- Spinners for async operations
+- Progress bars for batch operations
+- Clear success/failure indicators
+
+#### Help System
+- Comprehensive help for all commands: `mx <command> --help`
+- Examples in help output
+- Global help: `mx --help`
+- Command discovery: `mx` (no args shows available commands)
+
+#### Autocomplete (Future Enhancement)
+- Shell completion scripts for bash/zsh/fish
+- Command and option completion
+- Context-aware suggestions
+
+## Development Plan
+
+### Phase 1: Foundation (Week 1)
+**Goal**: Set up project infrastructure and core utilities
+
+- [ ] Initialize TypeScript project with package.json
+- [ ] Add `@memnexus-ai/contracts` dependency for API client
+- [ ] Configure TypeScript, ESLint, Prettier
+- [ ] Set up project structure (src/, tests/, docs/)
+- [ ] Implement configuration management (configstore)
+- [ ] Create API client wrapper around `@memnexus-ai/contracts`
+- [ ] Create authentication helpers
+- [ ] Set up error handling framework
+- [ ] Create output formatters (JSON, table, YAML)
+- [ ] Write basic tests for utilities
+
+### Phase 2: Core Commands (Week 2)
+**Goal**: Implement primary resource commands
+
+- [ ] Implement `auth` commands (login, logout, status)
+- [ ] Implement `config` commands (get, set, list, reset)
+- [ ] Implement `conversations start` command (**CRITICAL**: Required before memory creation)
+- [ ] Implement `memories` commands (CRUD + search, requires conversationId)
+- [ ] Implement `conversations` commands (list, get, timeline, search, by-topic)
+- [ ] Implement `facts` commands (CRUD + search)
+- [ ] Write tests for core commands
+- [ ] Create comprehensive help documentation
+
+### Phase 3: Advanced Commands (Week 3)
+**Goal**: Implement advanced features and graph operations
+
+- [ ] Implement `topics` commands (including graph operations)
+- [ ] Implement `communities` commands
+- [ ] Implement `patterns` commands
+- [ ] Implement `graphrag` commands
+- [ ] Implement `artifacts` commands
+- [ ] Implement `apikeys` commands
+- [ ] Implement `system` commands
+- [ ] Write tests for advanced commands
+
+### Phase 4: Polish & Distribution (Week 4)
+**Goal**: Prepare for release
+
+- [ ] Add interactive prompts for complex commands
+- [ ] Improve error messages and validation
+- [ ] Add progress indicators and spinners
+- [ ] Write comprehensive README with examples
+- [ ] Create usage documentation
+- [ ] Set up GitHub Actions workflow for publishing to GitHub Packages
+- [ ] Configure package.json for GitHub Packages distribution
+- [ ] Test installation and usage across platforms
+- [ ] Create release checklist and versioning strategy
+- [ ] Verify workflow publishes correctly on push to main
+- [ ] Optional: Create standalone binaries with pkg
+
+## Testing Strategy
+
+### Unit Tests
+- Test all utility functions (formatters, validators, config)
+- Test API client wrapper initialization
+- Test error handling and display logic
+- Test command argument parsing
+- Target: 80%+ code coverage
+
+### Integration Tests
+- Test commands against mock API Gateway endpoints
+- Test authentication flows (API key storage/retrieval)
+- Test configuration management (read/write/encrypt)
+- Test output formatting (JSON, table, YAML)
+- Mock `@memnexus-ai/contracts` responses for consistent testing
+
+### Manual Testing
+- Test on Linux, macOS, Windows
+- Test against real API Gateway (dev/staging environments)
+- Test direct connection to mx-core-api (local development)
+- Test edge cases and error scenarios
+- Verify help documentation accuracy
+- Test with different API key permissions
+
+## Success Metrics
+
+### Development Metrics
+- 100% endpoint coverage from mx-core-api
+- 80%+ unit test coverage
+- Zero TypeScript errors
+- Passing CI/CD pipeline
+
+### User Experience Metrics
+- Clear, helpful error messages
+- Intuitive command structure
+- Comprehensive documentation
+- Fast response times (<2s for typical operations)
+
+### Adoption Metrics (Post-Launch)
+- npm downloads
+- GitHub stars/issues
+- User feedback and feature requests
+- Community contributions
+
+## Distribution & Deployment
+
+### GitHub Packages (Primary Distribution)
+- Package name: `@memnexus-ai/cli`
+- Published to GitHub Packages registry: `https://npm.pkg.github.com`
+- Scoped to `@memnexus-ai` organization
+- Semantic versioning (SemVer)
+- Automated publishing via GitHub Actions
+- Git tags created for each release: `cli-v{version}`
+- Automatic GitHub Releases with changelog
+
+### Installation Methods
+```bash
+# Configure npm to use GitHub Packages for @memnexus-ai scope
+npm config set @memnexus-ai:registry https://npm.pkg.github.com
+
+# Authenticate with GitHub (requires GITHUB_TOKEN with read:packages permission)
+npm login --scope=@memnexus-ai --registry=https://npm.pkg.github.com
+
+# Install globally
+npm install -g @memnexus-ai/cli
+
+# Or install in project
+npm install --save-dev @memnexus-ai/cli
+
+# Use via npx (no installation)
+npx @memnexus-ai/cli memories list
+```
+
+### CI/CD Workflow
+The package is automatically published via GitHub Actions workflow (`.github/workflows/publish.yml`):
+
+**Triggers:**
+- Push to `main` branch (with relevant file changes)
+- Manual workflow dispatch with version bump (patch/minor/major)
+- Pull requests for validation only
+
+**Workflow Jobs:**
+1. **Validate** - Lint, build, test, and check package contents
+2. **Publish** - Publish to GitHub Packages (only on main/manual trigger)
+   - Checks if version already exists
+   - Publishes package to GitHub Packages
+   - Creates git tag (`cli-v{version}`)
+   - Creates GitHub Release with installation instructions
+
+**Version Management:**
+- Manual version bumps via workflow_dispatch input
+- Prevents duplicate publishes by checking existing versions
+- Follows existing pattern from `@memnexus-ai/contracts` package
+
+### package.json Configuration
+```json
+{
+  "name": "@memnexus-ai/cli",
+  "version": "1.0.0",
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com",
+    "@memnexus-ai:registry": "https://npm.pkg.github.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/memnexus-ai/memnexus.git",
+    "directory": "mx-cli"
+  }
+}
+```
+
+### Binary Distribution (Optional/Future)
+- Platform-specific binaries for users without Node.js
+- Hosted on GitHub Releases
+- Supported platforms: Linux (x64), macOS (x64, arm64), Windows (x64)
+- Built with `pkg` or similar tool
+
+## Future Enhancements
+
+### Version 1.1+
+- Shell autocomplete support (bash, zsh, fish)
+- Batch operations (bulk create, update, delete)
+- Import/export capabilities (JSON, CSV)
+- Dry-run mode for destructive operations
+- Verbose/debug logging mode
+- Plugins/extensions system
+
+### Version 2.0+
+- TUI (Terminal UI) mode with terminal-kit or blessed
+- Watch mode for real-time updates
+- Local caching for offline usage
+- GraphQL support (if API adds GraphQL)
+- WebSocket support for real-time features
+
+## Security Considerations
+
+### API Key Storage
+- Encrypt API keys before storing in config file
+- Use keytar or similar for OS-level keychain integration (future)
+- Never log API keys
+- Warn users about key exposure in scripts
+
+### HTTPS Enforcement
+- Always use HTTPS for API requests
+- Validate SSL certificates
+- Allow certificate bypass only with explicit flag (for development)
+
+### Input Sanitization
+- Validate all user inputs with Zod schemas
+- Prevent command injection
+- Escape special characters in outputs
+
+## Documentation Requirements
+
+### README.md
+- Installation instructions
+- Quick start guide
+- Basic usage examples
+- Configuration guide
+- Link to full documentation
+
+### docs/usage.md
+- Comprehensive command reference
+- Advanced usage patterns
+- Scripting examples
+- Troubleshooting guide
+
+### docs/development.md
+- Development setup
+- Contributing guidelines
+- Architecture overview
+- Testing guidelines
+
+### Inline Documentation
+- JSDoc comments for all public functions
+- Help text for all commands and options
+- Examples in command help output
+
+## Open Questions
+
+1. **Binary Distribution**: Should we prioritize standalone binaries in v1.0, or focus on npm distribution first?
+   - *Recommendation*: Focus on npm/GitHub Packages first, add binaries in v1.1+
+
+2. **Authentication**: Should we support JWT authentication from day one, or start with API keys only?
+   - *Recommendation*: Start with API keys only (simpler, matches current contracts package)
+
+3. **Caching**: Should we implement local caching of frequently accessed data to reduce API calls?
+   - *Recommendation*: No caching in v1.0, add in v1.1+ if needed
+
+4. **Telemetry**: Should we collect anonymous usage telemetry to improve the CLI (opt-in)?
+   - *Recommendation*: No telemetry in v1.0, consider for v2.0+
+
+5. **Versioning**: How should we handle CLI version compatibility with mx-core-api versions?
+   - *Recommendation*: Pin to compatible `@memnexus-ai/contracts` version in package.json
+   - Document required contracts version in README
+   - Use semantic versioning to indicate breaking changes
+
+6. **Contracts Package Updates**: How often should we update the `@memnexus-ai/contracts` dependency?
+   - *Recommendation*: Update on each CLI release to stay in sync with API changes
+   - Use `^` semver range to allow patch updates automatically
+
+## CLI-API Synchronization
+
+For maintaining sync between the CLI and API during development, see these comprehensive strategy documents:
+
+### [CLI-API Sync Strategy](./sync-strategy.md)
+How to keep types, versions, and contracts in sync:
+- OpenAPI specification as single source of truth
+- Automated SDK generation via `openapi-typescript`
+- Contract testing with Dredd/Prism
+- Semantic versioning with exact pinning in v1.0
+- Automated dependency updates via Dependabot
+- Breaking change detection with `oasdiff`
+
+### [Code Generation Strategy](./code-generation-strategy.md)
+How CLI command code is created/updated when APIs change:
+- Why types auto-sync but commands don't
+- Hybrid approach: scaffolding + manual implementation
+- Coverage detection to catch missing commands (Phase 2)
+- Command scaffold generator (Phase 3)
+- Metadata-driven commands via OpenAPI extensions (Phase 4)
+
+**TL;DR**: Types sync automatically via `@memnexus-ai/contracts`, but CLI commands require manual implementation in v1.0. Post-v1.0, we'll add scaffolding generators to speed this up.
+
+## Appendix
+
+### Reference Materials
+- **CLI-API Sync Strategy**: [docs/sync-strategy.md](./sync-strategy.md)
+  - Complete workflow for keeping CLI in sync with API changes
+  - Version management strategy
+  - Contract testing setup
+  - CI/CD integration
+- **@memnexus-ai/contracts package**: `/workspaces/memnexus/mx-api-gateway/contracts/`
+  - TypeScript SDK and API client (primary dependency)
+  - OpenAPI specification: `openapi.yaml` and `openapi.json`
+  - Auto-generated types: `src/generated/schema.ts`
+- **API Gateway configuration**: `/workspaces/memnexus/mx-api-gateway/config/kong.yaml`
+  - Kong routing and plugin configuration
+  - Endpoint definitions and authentication setup
+- **mx-core-api**: `/workspaces/memnexus/mx-core-api/`
+  - Backend API implementation
+  - Request/response schemas: `src/schemas/`
+  - Architecture docs: `docs/`
+
+### Inspiration & Prior Art
+- **AWS CLI** - Command structure and output formatting
+- **Heroku CLI** - User experience and interactive flows
+- **GitHub CLI (gh)** - Modern CLI patterns and help system
+- **Firebase CLI** - Configuration management
+- **Stripe CLI** - API key authentication patterns
+
+---
+
+**Document Version**: 1.0
+**Last Updated**: 2025-11-13
+**Author**: Claude Code
+**Status**: Draft - Pending Review