kimu-cli 0.1.0 → 1.0.0

package/docs/index.md

@@ -5,8 +5,10 @@ Welcome to the complete documentation for KIMU-CLI, the official command-line in
 ## 📖 Getting Started
 
 ### Essential Reading
+- [**Getting Started Guide**](getting-started.md) - ⭐ **Start here!** Complete installation and first project tutorial
+- [**Quick Reference**](quick-reference.md) - 🚀 Common commands and workflows at a glance
 - [Introduction to KIMU-CLI](intro.md) - Overview and core concepts
-- [Distribution & Installation Guide](distribution.md) - Installation, building, and publishing
+- [Distribution & Installation Guide](distribution.md) - Advanced installation, building, and publishing
 - [Command Reference](command-kimu.md) - Complete command overview and usage
 
 ## ⚡ Quick References
@@ -15,6 +17,9 @@ Welcome to the complete documentation for KIMU-CLI, the official command-line in
 | Command | Description | Documentation |
 |---------|-------------|---------------|
 | `create` | Create new KIMU projects | [📖 docs](commands/create.md) |
+| `new` | Create components from templates | [📖 docs](commands/new.md) |
+| `install` | Install modules and extensions | [📖 docs](commands/install.md) ✅ |
+| `list` | Browse and discover packages | [📖 docs](commands/list.md) ✅ |
 | `info` | Show project information | [📖 docs](commands/info.md) |
 | `version` | Show version information | [📖 docs](commands/version.md) |
 | `help` | Command help system | [📖 docs](commands/help.md) |
@@ -22,9 +27,7 @@ Welcome to the complete documentation for KIMU-CLI, the official command-line in
 ### Planned Commands (Coming Soon)
 | Command | Description | Documentation |
 |---------|-------------|---------------|
-| `install` | Install modules and extensions | [📖 docs](commands/install.md) ⏳ |
 | `remove` | Remove modules and extensions | [📖 docs](commands/remove.md) ⏳ |
-| `list` | Browse available packages | [📖 docs](commands/list.md) ⏳ |
 | `build` | Build for production | [📖 docs](commands/build.md) ⏳ |
 | `dev` | Development server | [📖 docs](commands/dev.md) ⏳ |
 | `serve` | Serve built project | [📖 docs](commands/serve.md) ⏳ |
@@ -33,16 +36,18 @@ Welcome to the complete documentation for KIMU-CLI, the official command-line in
 ## 🎯 Use Case Guides
 
 ### For New Users
-1. **First Time Setup**: Start with [Introduction](intro.md) to understand KIMU-CLI
-2. **Installation**: Follow the [Distribution Guide](distribution.md) for installation
-3. **Create Your First Project**: Use [`kimu create`](commands/create.md)
-4. **Learn the Commands**: Browse the [Command Reference](command-kimu.md)
+1. **First Time Setup**: Start with [**Getting Started Guide**](getting-started.md) ⭐
+2. **Understand the Tool**: Read the [Introduction](intro.md) to understand KIMU-CLI
+3. **Installation Methods**: Follow the [Distribution Guide](distribution.md) for advanced options
+4. **Create Your First Project**: Use [`kimu create`](commands/create.md)
+5. **Learn the Commands**: Browse the [Command Reference](command-kimu.md)
 
 ### For Developers
-1. **Project Setup**: Use [`kimu create`](commands/create.md) and [`kimu info`](commands/info.md)
-2. **Development Workflow**: Plan ahead with [`kimu dev`](commands/dev.md) and [`kimu build`](commands/build.md) docs
-3. **Package Management**: Understand future [`kimu install`](commands/install.md) and [`kimu list`](commands/list.md)
-4. **Troubleshooting**: Prepare for [`kimu doctor`](commands/doctor.md) diagnostics
+1. **Quick Start**: Follow [Getting Started](getting-started.md) for complete workflow
+2. **Project Setup**: Use [`kimu create`](commands/create.md) and [`kimu info`](commands/info.md)
+3. **Development**: Use `npm run dev` for hot reload development
+4. **Building**: Use `npm run build` for production builds
+5. **Package Management**: Future [`kimu install`](commands/install.md) and [`kimu list`](commands/list.md)
 
 ### For Maintainers
 1. **Building and Distribution**: Follow [Distribution Guide](distribution.md)
@@ -54,36 +59,51 @@ Welcome to the complete documentation for KIMU-CLI, the official command-line in
 ```
 docs/
 ├── index.md                 # This file - documentation index
+├── getting-started.md       # ⭐ Complete installation and tutorial
 ├── intro.md                 # Introduction and overview  
 ├── command-kimu.md         # Complete command reference
-├── distribution.md         # Installation and distribution
+├── distribution.md         # Advanced installation and distribution
 └── commands/               # Individual command documentation
-    ├── create.md           # ✅ Available
-    ├── info.md             # ✅ Available  
-    ├── version.md          # ✅ Available
-    ├── help.md             # ✅ Available
-    ├── install.md          # ⏳ Planned
-    ├── remove.md           # ⏳ Planned
-    ├── list.md             # ⏳ Planned
-    ├── build.md            # ⏳ Planned
-    ├── dev.md              # ⏳ Planned
-    ├── serve.md            # ⏳ Planned
-    └── doctor.md           # ⏳ Planned
+    ├── create.md           # ✅ Available - Create new projects
+    ├── info.md             # ✅ Available - Project information
+    ├── version.md          # ✅ Available - Version information
+    ├── help.md             # ✅ Available - Help system
+    ├── install.md          # ⏳ Planned - Install modules/extensions
+    ├── remove.md           # ⏳ Planned - Remove packages
+    ├── list.md             # ⏳ Planned - List packages
+    ├── build.md            # ⏳ Planned - Build for production
+    ├── dev.md              # ⏳ Planned - Development server
+    ├── serve.md            # ⏳ Planned - Serve built project
+    └── doctor.md           # ⏳ Planned - Project diagnostics
 ```
 
 ## 🚀 Quick Start Examples
 
-### Create and Setup New Project
+### Installation
+
+**Global Installation (Recommended)**
 ```bash
-# Install KIMU-CLI globally
 npm install -g kimu-cli
+```
 
+**Using npx (No Installation)**
+```bash
+npx kimu-cli create my-awesome-app
+```
+
+### Create and Setup New Project
+```bash
 # Create new project
 kimu create my-awesome-app --git
 
-# Navigate and check project
+# Navigate to project
 cd my-awesome-app
+
+# Check project info
 kimu info --verbose
+
+# Start development server
+npm run dev
 ```
 
 ### Get Help and Information
@@ -94,10 +114,20 @@ kimu help
 # Get specific command help
 kimu create --help
 
-# Check versions
+# Check CLI version
+kimu --version
+
+# Detailed version info
 kimu version --verbose
 ```
 
+## 📦 NPM Package
+
+- **Package**: [kimu-cli on npm](https://www.npmjs.com/package/kimu-cli)
+- **Repository**: [GitHub - UnicoVerso/kimu-cli](https://github.com/UnicoVerso/kimu-cli)
+- **Current Version**: Check with `kimu --version`
+- **License**: MPL-2.0
+
 ## 🔄 Status Legend
 
 - ✅ **Available**: Command is implemented and ready to use

package/docs/intro.md

@@ -27,6 +27,7 @@ KIMU-CLI follows these principles:
 
 ### Project Management
 - `kimu create` - Create new KIMU projects
+- `kimu new` - Create components from templates (extensions, modules)
 - `kimu info` - Show project information and status
 - `kimu doctor` - Run project health diagnostics
 
@@ -46,25 +47,46 @@ KIMU-CLI follows these principles:
 
 ## Getting Started
 
-1. **Install KIMU-CLI globally**:
-   ```bash
-   npm install -g kimu-cli
-   ```
+### Installation
+
+**Option 1: Global Installation (Recommended)**
+```bash
+npm install -g kimu-cli
+```
+
+**Option 2: Use with npx (No Installation)**
+```bash
+npx kimu-cli create my-first-app
+```
+
+**Verify Installation**
+```bash
+kimu --version
+kimu --help
+```
 
-2. **Create your first project**:
+### Quick Start
+
+1. **Create your first project**:
    ```bash
    kimu create my-first-app
    cd my-first-app
    ```
 
-3. **Start developing**:
+2. **Install dependencies** (if not done automatically):
+   ```bash
+   npm install
+   ```
+
+3. **Start development server**:
    ```bash
-   kimu dev
+   npm run dev
    ```
+   Your app will be available at `http://localhost:5173/`
 
 4. **Build for production**:
    ```bash
-   kimu build
+   npm run build
    ```
 
 ## System Requirements

package/docs/quick-reference.md

@@ -0,0 +1,335 @@
+# KIMU-CLI Quick Reference
+
+A quick reference guide for the most common KIMU-CLI commands and workflows.
+
+## Installation
+
+```bash
+# Global installation (recommended)
+npm install -g kimu-cli
+
+# Check installation
+kimu --version
+
+# Update to latest version
+npm update -g kimu-cli
+```
+
+## Project Creation
+
+```bash
+# Basic project creation
+kimu create my-app
+
+# With git initialization
+kimu create my-app --git
+
+# Skip npm install (manual installation later)
+kimu create my-app --no-install
+
+# Force overwrite existing directory
+kimu create my-app --force
+
+# Using npx (no global installation)
+npx kimu-cli create my-app
+```
+
+## Component Generation
+
+```bash
+# Create new extension
+kimu new extension my-feature
+
+# Create new module
+kimu new module analytics
+
+# With custom path
+kimu new extension my-feature --path src/extensions/custom
+
+# Force overwrite
+kimu new extension my-feature --force
+
+# Skip auto-registration
+kimu new module analytics --no-register
+```
+
+## Project Information
+
+```bash
+# Basic project info
+kimu info
+
+# Detailed information
+kimu info --verbose
+
+# JSON output (for scripts)
+kimu info --json
+```
+
+## Version Information
+
+```bash
+# CLI version
+kimu --version
+
+# Detailed version info
+kimu version --verbose
+```
+
+## Help System
+
+```bash
+# General help
+kimu --help
+
+# Command-specific help
+kimu create --help
+kimu info --help
+kimu version --help
+
+# Help command
+kimu help
+kimu help create
+```
+
+## NPM Scripts (After Project Creation)
+
+Once you've created a project with `kimu create`, use these npm scripts:
+
+```bash
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+
+# Preview production build
+npm run preview
+
+# Run linter
+npm run lint
+
+# Generate dev build config
+npm run generate-config:dev
+
+# Generate production build config
+npm run generate-config:prod
+```
+
+## Common Workflows
+
+### 1. Start a New Project
+```bash
+# Create project
+kimu create my-project --git
+
+# Navigate to it
+cd my-project
+
+# Start development
+npm run dev
+```
+
+### 2. Check Project Details
+```bash
+# Navigate to project
+cd my-project
+
+# View project information
+kimu info --verbose
+```
+
+### 3. Build and Deploy
+```bash
+# Navigate to project
+cd my-project
+
+# Generate production config
+npm run generate-config:prod
+
+# Build for production
+npm run build
+
+# Test production build locally
+npm run preview
+
+# Deploy dist/ folder to your hosting
+```
+
+### 4. Update KIMU CLI
+```bash
+# Check current version
+kimu --version
+
+# Update to latest
+npm update -g kimu-cli
+
+# Verify update
+kimu --version
+```
+
+## Project Structure Reference
+
+```
+my-project/
+├── src/
+│   ├── core/              # KIMU framework core
+│   ├── extensions/        # UI extensions
+│   ├── modules/           # Modules (router, i18n)
+│   └── main.ts            # Application entry
+├── public/                # Static assets
+├── scripts/               # Build scripts
+├── dist/                  # Build output
+├── kimu.config.json       # KIMU configuration
+├── kimu-build-config.ts   # Build config (generated)
+├── package.json           # Dependencies
+├── tsconfig.json          # TypeScript config
+├── vite.config.ts         # Vite config
+└── README.md              # Project docs
+```
+
+## Key Configuration Files
+
+### kimu.config.json
+```json
+{
+  "name": "my-project",
+  "version": "1.0.0",
+  "kimuCore": "^0.4.0",
+  "modules": {
+    "installed": [],
+    "registry": "https://github.com/unicoverso/kimu-modules"
+  },
+  "extensions": {
+    "installed": ["kimu-home"],
+    "main": "kimu-home"
+  }
+}
+```
+
+### package.json (key scripts)
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint src/**/*.ts"
+  }
+}
+```
+
+## Environment Variables
+
+Create a `.env` file in your project root:
+
+```bash
+# Development
+VITE_API_URL=http://localhost:3000
+VITE_ENV=development
+
+# Production
+VITE_API_URL=https://api.myapp.com
+VITE_ENV=production
+```
+
+Access in code:
+```typescript
+const apiUrl = import.meta.env.VITE_API_URL;
+```
+
+## Troubleshooting
+
+### Command not found: kimu
+```bash
+# Check npm global bin location
+npm config get prefix
+
+# Add to PATH (bash/zsh)
+echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### Port already in use
+```bash
+# Kill process on port 5173
+lsof -ti:5173 | xargs kill -9
+
+# Or use different port
+vite --port 3000
+```
+
+### Clean install
+```bash
+# Remove dependencies and build
+rm -rf node_modules dist
+
+# Reinstall
+npm install
+
+# Rebuild
+npm run build
+```
+
+### Update dependencies
+```bash
+# Check for updates
+npm outdated
+
+# Update all dependencies
+npm update
+
+# Update specific package
+npm update kimu-core
+```
+
+## Tips and Tricks
+
+### Faster npm installs
+```bash
+# Use npm ci for clean installs (faster)
+npm ci
+
+# Or use pnpm (faster alternative)
+npm install -g pnpm
+pnpm install
+```
+
+### Development mode with custom port
+```bash
+# Edit package.json
+"dev": "vite --port 3000 --host"
+
+# Or use CLI flag
+npm run dev -- --port 3000
+```
+
+### Production build analysis
+```bash
+# Install bundle analyzer
+npm install --save-dev rollup-plugin-visualizer
+
+# Add to vite.config.ts for build stats
+```
+
+### Git workflow
+```bash
+# Initial commit (if created with --git)
+git add .
+git commit -m "Initial commit"
+
+# Add remote and push
+git remote add origin <your-repo-url>
+git push -u origin main
+```
+
+## Next Steps
+
+- **Documentation**: [Full Docs](../docs/index.md)
+- **Getting Started**: [Complete Tutorial](getting-started.md)
+- **Commands**: [Command Reference](command-kimu.md)
+- **Examples**: [KIMU Examples](https://github.com/UnicoVerso/kimu-extensions-example)
+
+---
+
+Need more help? Check the [complete documentation](index.md) or [open an issue](https://github.com/UnicoVerso/kimu-cli/issues).