@memnexus-ai/cli 0.1.1 → 0.1.4

package/docs/README.md

@@ -1,219 +0,0 @@
-# MemNexus CLI Documentation
-
-Welcome to the mx-cli documentation! This directory contains comprehensive planning and strategy documents for building and maintaining the CLI.
-
-## Core Documents
-
-### 📋 [Product Requirements Document (PRD)](./prd.md)
-**Complete specification for the CLI project**
-
-What's inside:
-- Technology stack and dependencies
-- Architecture and system design
-- All CLI commands and features
-- Development roadmap (4-week plan)
-- Testing strategy
-- Distribution via GitHub Packages
-
-**Start here** if you want to understand what the CLI does and how it's built.
-
----
-
-### 🔄 [CLI-API Sync Strategy](./sync-strategy.md)
-**How to keep CLI in sync with API changes**
-
-What's inside:
-- OpenAPI as single source of truth
-- Automated SDK generation workflow
-- Contract testing with Dredd/Prism
-- Version management (SemVer)
-- CI/CD integration
-- Breaking change detection
-
-**Read this** to understand how type safety and API compatibility is maintained.
-
----
-
-### 🤖 [Code Generation Strategy](./code-generation-strategy.md)
-**How CLI commands are created when APIs change**
-
-What's inside:
-- Why full auto-generation doesn't work for CLIs
-- Hybrid approach: scaffolding + manual implementation
-- Coverage detection to catch missing commands
-- Command scaffold generator (future)
-- Metadata-driven commands via OpenAPI extensions
-
-**Read this** to understand why CLI commands are manual in v1.0 and the roadmap for semi-automation.
-
----
-
-## Quick Reference
-
-### The Three-Layer Architecture
-
-```
-┌─────────────────────────────────┐
-│  OpenAPI Specification          │  Single source of truth
-└────────────┬────────────────────┘
-             │ generates
-             ▼
-┌─────────────────────────────────┐
-│  @memnexus-ai/contracts         │  TypeScript SDK
-│  - Auto-generated types         │  (Auto-sync)
-│  - API client methods           │
-└────────────┬────────────────────┘
-             │ dependency
-             ▼
-┌─────────────────────────────────┐
-│  @memnexus-ai/cli               │  CLI tool
-│  - Commands (manual)            │  (Manual for v1.0)
-│  - Business logic               │
-└─────────────────────────────────┘
-```
-
-### What's Automated vs. Manual
-
-| Aspect | Status | Tool/Process |
-|--------|--------|-------------|
-| **TypeScript types** | ✅ Automated | `openapi-typescript` |
-| **API client methods** | ✅ Automated | `@memnexus-ai/contracts` build |
-| **Breaking change detection** | ✅ Automated | `oasdiff` (future) |
-| **Dependency updates** | ✅ Automated | Dependabot (future) |
-| **Contract testing** | ✅ Automated | Dredd/Prism (future) |
-| **CLI command structure** | ❌ Manual | Developer writes code |
-| **Business logic** | ❌ Manual | Developer writes code |
-| **Help text** | ❌ Manual | Developer writes code |
-| **Output formatting** | ❌ Manual | Developer writes code |
-
-### Key Decisions
-
-1. **TypeScript + Node.js** - Leverage existing codebase and contracts package
-2. **Via API Gateway** - All requests go through Kong (production/staging)
-3. **Exact version pinning** - Pin `@memnexus-ai/contracts` version in v1.0 for stability
-4. **Manual commands for v1.0** - Build scaffolding generator after patterns stabilize
-5. **GitHub Packages** - Primary distribution method
-
-### Development Workflow
-
-**When an API endpoint is added/changed:**
-
-```mermaid
-graph LR
-    A[Change API] --> B[Update OpenAPI]
-    B --> C[Publish contracts]
-    C --> D[Update CLI dependency]
-    D --> E[Implement command]
-    E --> F[Test & publish CLI]
-```
-
-**Detailed steps**:
-1. Developer changes mx-core-api code
-2. Developer updates OpenAPI spec (`contracts/openapi.yaml`)
-3. Contracts package auto-generates types and publishes
-4. CLI updates `@memnexus-ai/contracts` dependency
-5. **Developer manually implements CLI command** (for v1.0)
-6. CLI is tested and published via GitHub Actions
-
-### Phased Automation Plan
-
-#### Phase 1: Manual (Weeks 1-4) ✅ Current
-- Use contracts for types
-- Write commands manually
-- Establish patterns
-
-#### Phase 2: Detection (Weeks 5-6) 🎯 Next
-- Build coverage checker
-- Alert on missing commands
-- CI/CD integration
-
-#### Phase 3: Scaffolding (Month 2) ⏸️ Future
-- Build command generator
-- Auto-create skeletons
-- Developer fills in logic
-
-#### Phase 4: Metadata-Driven (Month 3+) ⏸️ Future
-- OpenAPI extensions for CLI
-- Auto-generate help text
-- Near-automatic updates
-
-## Common Questions
-
-### Q: Do types update automatically when the API changes?
-**A**: Yes! When `@memnexus-ai/contracts` is updated, you get new TypeScript types automatically.
-
-### Q: Do CLI commands update automatically?
-**A**: No (for v1.0). Developers must manually implement new commands. However:
-- Coverage detection will alert when commands are missing (Phase 2)
-- Scaffolding generator will create boilerplate (Phase 3)
-- Metadata-driven approach will minimize manual work (Phase 4)
-
-### Q: Why not fully auto-generate CLI commands?
-**A**:
-- No mature tools for TypeScript/Commander.js generation
-- Generated code loses flexibility and polish
-- Help text, examples, and UX require human touch
-- Business logic is unique per endpoint
-
-See [Code Generation Strategy](./code-generation-strategy.md#evaluated-solutions) for detailed analysis.
-
-### Q: How do I know if the CLI is out of sync with the API?
-**A**:
-- **v1.0**: Manual tracking
-- **Phase 2+**: Automated coverage checks in CI/CD
-- **Future**: GitHub bot creates PRs when endpoints are added
-
-### Q: What happens when there's a breaking API change?
-**A**:
-1. `oasdiff` detects breaking change in CI/CD
-2. Contracts package bumps MAJOR version (e.g., 1.0.0 → 2.0.0)
-3. CLI must update code to handle new contract
-4. CLI bumps MAJOR version too
-5. Migration guide documents changes
-
-See [Sync Strategy - Breaking Changes](./sync-strategy.md#detecting-breaking-changes).
-
-### Q: Can I point the CLI directly at mx-core-api instead of the gateway?
-**A**: Yes! For local development:
-```bash
-export MX_API_URL=http://localhost:3000
-mx memories list
-```
-
-Default is API Gateway (`https://api.memnexus.io` in production).
-
-## Next Steps
-
-### For Contributors
-1. Read [PRD](./prd.md) to understand the project
-2. Check [Development Plan](./prd.md#development-plan) for current priorities
-3. See [Sync Strategy](./sync-strategy.md) for workflow details
-
-### For Maintainers
-1. Implement Phase 2 coverage detection after v1.0
-2. Monitor contracts package updates
-3. Keep documentation in sync with implementation
-
-### For Users
-- Installation and usage docs will be in `../README.md` (root of mx-cli)
-- API reference will be in `../docs/api-reference.md` (future)
-- Examples will be in `../examples/` (future)
-
-## Document Status
-
-| Document | Version | Last Updated | Status |
-|----------|---------|--------------|--------|
-| [prd.md](./prd.md) | 1.0 | 2025-11-13 | ✅ Complete |
-| [sync-strategy.md](./sync-strategy.md) | 1.0 | 2025-11-13 | ✅ Complete |
-| [code-generation-strategy.md](./code-generation-strategy.md) | 1.0 | 2025-11-13 | ✅ Complete |
-
-## Contributing
-
-Found an issue or have a suggestion? Please:
-1. Open an issue in the GitHub repository
-2. Reference the relevant document
-3. Propose specific changes
-
----
-
-**Questions?** Open an issue or reach out to the MemNexus team.