forgestack-os-cli 0.3.5 → 0.3.6

package/README.md

@@ -1,441 +1,424 @@
-# ForgeStack OS CLI
+<p align="center">
+  <img src="https://raw.githubusercontent.com/halloffame12/forgestack-os/main/docs/assets/logo.svg" alt="ForgeStack OS Logo" width="80" height="80" />
+</p>
+
+<h1 align="center">ForgeStack OS CLI</h1>
+
+<p align="center">
+  <strong>Generate production-ready full-stack SaaS projects with one command.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/forgestack-os-cli"><img src="https://img.shields.io/npm/v/forgestack-os-cli?style=flat-square&color=0891b2&label=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/forgestack-os-cli"><img src="https://img.shields.io/npm/dm/forgestack-os-cli?style=flat-square&color=0891b2" alt="npm downloads" /></a>
+  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License" />
+  <img src="https://img.shields.io/badge/Node.js-18+-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js" />
+  <img src="https://img.shields.io/badge/TypeScript-5.7-3178c6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" />
+</p>
+
+<p align="center">
+  <a href="#-installation">Installation</a> •
+  <a href="#-quick-start">Quick Start</a> •
+  <a href="#-commands">Commands</a> •
+  <a href="#-examples">Examples</a> •
+  <a href="#-troubleshooting">Help</a>
+</p>
 
-Generate production-ready full-stack SaaS projects with one command.
+---
 
-## Installation
+## 📦 Installation
 
-### Option 1: Using npx (Recommended - No Installation Needed)
+### Using npx (Recommended — No Install Required)
 
 ```bash
 npx forgestack-os-cli create my-app
 ```
 
-No setup required! The fastest way to get started. The CLI is downloaded and run on the fly.
-
-### Option 2: Install Globally
+### Global Installation
 
 ```bash
 npm install -g forgestack-os-cli
+forgestack-os-cli create my-app
 ```
 
-Then create projects using:
+<details>
+<summary><strong>🔧 Troubleshooting global install</strong></summary>
 
-```bash
-forgestack-os-cli create my-app
-```
+If you get `command not found` after global install:
 
-**Note on Global Install:** After installing globally, the command `forgestack-os-cli` should be in your PATH. If you get `command not found` errors:
+1. Check your npm bin directory:
 
-1. Verify your npm bin directory is in PATH:
    ```bash
    npm config get prefix
    ```
-2. Add it to PATH if needed:
-   - **Windows (PowerShell):** `[System.Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Users\YourUsername\AppData\Roaming\npm", [System.EnvironmentVariableTarget]::User)`
-   - **macOS/Linux:** Add `export PATH="~/.npm-global/bin:$PATH"` to `~/.bash_profile` or `~/.zshrc`
+
+2. Add it to your PATH:
+   - **Windows (PowerShell)**:
+     ```powershell
+     [System.Environment]::SetEnvironmentVariable("Path", "$env:Path;$(npm config get prefix)", [System.EnvironmentVariableTarget]::User)
+     ```
+   - **macOS/Linux**:
+     ```bash
+     export PATH="$(npm config get prefix)/bin:$PATH"
+     ```
 
 3. Verify installation:
    ```bash
    forgestack-os-cli --version
    ```
 
-## Quick Start
+</details>
 
-**Fastest way to create a project:**
+---
+
+## ⚡ Quick Start
 
 ```bash
-# Interactive mode - we'll ask you questions
-npx forgestack-os-cli create my-app
+# Interactive mode — answer prompts to configure your stack
+npx forgestack-os-cli create my-saas-app
 
-# With a preset - production-ready stack
-npx forgestack-os-cli create my-enterprise --preset next-nest-clerk-pg
+# Use a preset for instant setup
+npx forgestack-os-cli create my-app --preset next-nest-clerk-pg
 
-# With specific flags
-npx forgestack-os-cli create my-api --frontend nextjs --backend nestjs --auth supabase --database postgresql --docker
+# Specify options directly
+npx forgestack-os-cli create my-app \
+  --frontend nextjs \
+  --backend nestjs \
+  --auth clerk \
+  --database postgresql \
+  --docker
 ```
 
-## Usage
+**In 30 seconds**, you get:
 
-```bash
-forgestack-os-cli create <project-name> [options]
-```
+- ✅ Full authentication system
+- ✅ Database with migrations
+- ✅ API documentation (Swagger)
+- ✅ Docker configuration
+- ✅ TypeScript everywhere
+
+---
 
-Or with npx:
+## 🧰 Commands
+
+### `create` — Generate a New Project
 
 ```bash
 npx forgestack-os-cli create <project-name> [options]
 ```
 
-### Available Options
-
-| Option           | Values                                                                            | Description                             |
-| ---------------- | --------------------------------------------------------------------------------- | --------------------------------------- |
-| `--frontend`     | `react-vite` \| `nextjs` \| `vue-vite` \| `sveltekit`                             | Frontend framework                      |
-| `--backend`      | `express` \| `fastify` \| `nestjs` \| `bun-elysia` \| `go-fiber`                  | Backend framework                       |
-| `--auth`         | `jwt` \| `clerk` \| `supabase` \| `authjs` \| `firebase`                          | Authentication provider                 |
-| `--database`     | `postgresql` \| `mongodb` \| `mysql` \| `sqlite` \| `supabase-db`                 | Database                                |
-| `--api`          | `rest` \| `graphql` \| `trpc`                                                     | API style                               |
-| `--preset`       | `next-nest-clerk-pg` \| `react-express-jwt-mongo` \| `next-fastify-supabase-trpc` | Predefined stack                        |
-| `--stack`        | JSON string                                                                       | Full stack config as JSON               |
-| `--docker`       | -                                                                                 | Include Docker configuration            |
-| `--no-docker`    | -                                                                                 | Skip Docker configuration (default)     |
-| `--multi-tenant` | -                                                                                 | Enable multi-tenancy scaffolding        |
-| `--skip-install` | -                                                                                 | Skip npm install after project creation |
-| `--skip-git`     | -                                                                                 | Skip git initialization                 |
-
-## Examples
+<table>
+<tr><th>Option</th><th>Values</th><th>Description</th></tr>
+<tr><td><code>--frontend</code></td><td><code>react-vite</code> | <code>nextjs</code> | <code>vue-vite</code> | <code>sveltekit</code></td><td>Frontend framework</td></tr>
+<tr><td><code>--backend</code></td><td><code>express</code> | <code>fastify</code> | <code>nestjs</code> | <code>bun-elysia</code> | <code>go-fiber</code></td><td>Backend framework</td></tr>
+<tr><td><code>--auth</code></td><td><code>jwt</code> | <code>clerk</code> | <code>supabase</code> | <code>authjs</code> | <code>firebase</code></td><td>Authentication</td></tr>
+<tr><td><code>--database</code></td><td><code>postgresql</code> | <code>mongodb</code> | <code>mysql</code> | <code>sqlite</code></td><td>Database</td></tr>
+<tr><td><code>--api</code></td><td><code>rest</code> | <code>graphql</code> | <code>trpc</code></td><td>API style</td></tr>
+<tr><td><code>--preset</code></td><td><code>next-nest-clerk-pg</code> | <code>react-express-jwt-mongo</code> | <code>next-fastify-supabase-trpc</code></td><td>Preset stack</td></tr>
+<tr><td><code>--docker</code></td><td>—</td><td>Include Docker config</td></tr>
+<tr><td><code>--multi-tenant</code></td><td>—</td><td>Enable multi-tenancy</td></tr>
+<tr><td><code>--skip-install</code></td><td>—</td><td>Skip npm install</td></tr>
+<tr><td><code>--skip-git</code></td><td>—</td><td>Skip git init</td></tr>
+</table>
 
-### Interactive Mode (Recommended)
+---
+
+### `doctor` — Validate Environment ✨ NEW
+
+Diagnose your dev environment and catch issues before they slow you down.
 
 ```bash
-npx forgestack-os-cli create my-saas
+npx forgestack-os-cli doctor [options]
 ```
 
-You'll be guided through selecting your stack options with interactive prompts.
-
-### Using Presets
+<table>
+<tr><th>Option</th><th>Description</th></tr>
+<tr><td><code>--lint</code></td><td>Run ESLint and TypeScript checks</td></tr>
+<tr><td><code>--json</code></td><td>Output as JSON for CI/CD pipelines</td></tr>
+<tr><td><code>--fix</code></td><td>Generate <code>.env.missing</code> report</td></tr>
+<tr><td><code>--cwd &lt;path&gt;</code></td><td>Check a specific directory</td></tr>
+</table>
 
-**Next.js + NestJS + Clerk + PostgreSQL (Full-featured):**
+**Example Output:**
 
-```bash
-npx forgestack-os-cli create my-enterprise --preset next-nest-clerk-pg
 ```
+🩺 ForgeStack Doctor Report
 
-**React + Express + JWT + MongoDB (Simple SPA):**
+📋 Node.js & Package Managers
 
-```bash
-npx forgestack-os-cli create my-app --preset react-express-jwt-mongo
-```
+✅ Node.js: Node version: 20.2.0
+✅ npm: npm version: 10.2.0
+⏭️ pnpm: pnpm is not installed (optional)
 
-**Next.js + Fastify + Supabase + tRPC (Modern fullstack):**
+📋 Environment Variables
 
-```bash
-npx forgestack-os-cli create my-trpc-app --preset next-fastify-supabase-trpc
-```
+❌ Missing .env Variables: DATABASE_URL, JWT_SECRET
+   💡 Fix: Add the missing variables to your .env file
 
-### Using Flags
+📋 Database Connectivity
 
-**RESTful API with React + Express:**
+✅ PostgreSQL Connection: Successfully connected to PostgreSQL
 
-```bash
-npx forgestack-os-cli create my-rest-api \
-  --frontend react-vite \
-  --backend express \
-  --auth jwt \
-  --database postgresql \
-  --api rest
-```
+📋 Prisma ORM
 
-**GraphQL Backend with Vue:**
+✅ Prisma Schema: Prisma schema is valid
+✅ Prisma Client: Prisma client is generated
+⚠️ Prisma Migrations: Pending migrations detected
+   💡 Fix: Run: npx prisma migrate dev
 
-```bash
-npx forgestack-os-cli create my-graphql-app \
-  --frontend vue-vite \
-  --backend nestjs \
-  --auth firebase \
-  --database mongodb \
-  --api graphql \
-  --docker
-```
+📋 Docker
 
-**Minimal Setup (SQLite + No Docker):**
+✅ Docker: Docker installed: 24.0.7
+✅ Docker Daemon: Docker daemon is running
+✅ Docker Compose: Docker Compose V2: 2.23.0
 
-```bash
-npx forgestack-os-cli create my-minimal-app \
-  --frontend react-vite \
-  --backend express \
-  --auth jwt \
-  --database sqlite \
-  --no-docker
-```
+📋 Port Availability
 
-### Using JSON Stack Config
+❌ Backend (port 3000): Port 3000 is used by node (PID: 12345)
+   💡 Fix: Stop the process or use a different port. Kill: taskkill /PID 12345 /F
+✅ Frontend (port 5173): Port 5173 is available
 
-Provide complete configuration as a JSON string:
+───────────────────────────────────────────────────────────
 
-```bash
-npx forgestack-os-cli create my-custom-stack --stack '{
-  "frontend": "nextjs",
-  "backend": "fastify",
-  "auth": "supabase",
-  "database": "supabase-db",
-  "apiStyle": "trpc",
-  "docker": true,
-  "multiTenant": true
-}'
-```
+📊 Summary:
 
-**Multi-tenancy with Docker:**
+   Total Checks: 12
+   Passed: 8
+   Warnings: 1
+   Failed: 2
+   Skipped: 1
 
-```bash
-npx forgestack-os-cli create my-multitenant-app \
-  --preset next-nest-clerk-pg \
-  --multi-tenant \
-  --docker
+✖ Found 2 critical issue(s) that need to be fixed.
 ```
 
-**Skip Dependency Installation:**
+**Checks Performed:**
 
-```bash
-npx forgestack-os-cli create my-app --preset next-nest-clerk-pg --skip-install
-cd my-app
-npm install  # Install later when you're ready
+| Check          | Description                                        |
+| -------------- | -------------------------------------------------- |
+| 🟢 Node.js     | Version against `.nvmrc` or `package.json` engines |
+| 🟢 npm/pnpm    | Package manager availability                       |
+| 🟢 Environment | Missing variables from `.env.example`              |
+| 🟢 Database    | PostgreSQL, MongoDB, MySQL, SQLite connectivity    |
+| 🟢 Prisma      | Client generation, schema validation, migrations   |
+| 🟢 Docker      | Installation, daemon status, Compose availability  |
+| 🟢 Ports       | Backend (3000) and frontend (5173) availability    |
+| 🟢 ESLint      | Linting issues (with `--lint`)                     |
+| 🟢 TypeScript  | Compile errors (with `--lint`)                     |
+
+**CI/CD Integration:**
+
+```yaml
+# GitHub Actions
+- name: Validate Environment
+  run: |
+    npx forgestack-os-cli doctor --json > doctor-report.json
+    if [ $(jq '.summary.failed' doctor-report.json) -gt 0 ]; then
+      exit 1
+    fi
 ```
 
-## Additional Commands
+---
 
-### `organize` - File Organization Utility
+### `organize` — File Organization Utility
 
-Organize files in a folder by type or date, with optional duplicate detection. Supports MD5-based duplicate identification and automatic system folder exclusion for performance.
+Organize files by type or date with duplicate detection.
 
 ```bash
 npx forgestack-os-cli organize <folder-path> [options]
 ```
 
-**Options:**
-- `--strategy <type>` - Organization strategy: `type` (default) or `date`
-- `--duplicates` - Move duplicate files to a `Duplicates` folder
-
-**File Categories (when using `--strategy type`):**
-- **Images**: jpg, png, gif, svg, webp, bmp, ico
-- **Documents**: pdf, doc, docx, txt, xlsx, csv, md
-- **Videos**: mp4, mkv, avi, mov, wmv, flv
-- **Audio**: mp3, wav, flac, aac, m4a, ogg
-- **Code**: js, ts, py, java, cpp, go, rs, rb
-- **Archives**: zip, rar, 7z, tar, gz, bz2
-- **Data**: json, xml, yaml, sql, db, sqlite
-- **Executables**: exe, msi, app, deb, rpm
-- **Others**: All other file types
-
-**Date Format (when using `--strategy date`):**
-Files organized into folders using format: `YYYY-MM` (e.g., `2026-01`, `2025-12`)
-
-**Features:**
-- ✅ Automatically skips system folders (node_modules, .git, dist, build, .next, .env, .DS_Store, .vscode)
-- ✅ MD5-based duplicate detection (prevents moving the same file twice)
-- ✅ Graceful error handling for permission denied or inaccessible files
-- ✅ Summary report showing total files organized and categories
-- ✅ Interactive prompts if options not provided
-
-**Examples:**
+<table>
+<tr><th>Option</th><th>Description</th></tr>
+<tr><td><code>--strategy &lt;type&gt;</code></td><td><code>type</code> (by extension) or <code>date</code> (by YYYY-MM)</td></tr>
+<tr><td><code>--duplicates</code></td><td>Move duplicate files to <code>Duplicates/</code></td></tr>
+</table>
+
+**File Categories:**
+
+- 📷 **Images**: jpg, png, gif, svg, webp, bmp, ico
+- 📄 **Documents**: pdf, doc, docx, txt, xlsx, csv, md
+- 🎬 **Videos**: mp4, mkv, avi, mov, wmv, flv
+- 🎵 **Audio**: mp3, wav, flac, aac, m4a, ogg
+- 💻 **Code**: js, ts, py, java, cpp, go, rs, rb
+- 📦 **Archives**: zip, rar, 7z, tar, gz, bz2
+- 📊 **Data**: json, xml, yaml, sql, db, sqlite
+- ⚙️ **Executables**: exe, msi, app, deb, rpm
+
+**Example:**
 
 ```bash
-# Organize by file type with duplicate detection
+# Organize Downloads by file type with duplicate detection
 npx forgestack-os-cli organize ~/Downloads --strategy type --duplicates
 
 # Organize photos by month
 npx forgestack-os-cli organize ~/Pictures --strategy date
-
-# Interactive mode (prompts for folder and options)
-npx forgestack-os-cli organize
-
-# Organize current directory
-npx forgestack-os-cli organize .
 ```
 
-**Output Example:**
-```
-✓ Found and organized 1,250 files
-✓ Categories:
-  - Images: 450 files
-  - Documents: 280 files
-  - Videos: 320 files
-  - Code: 145 files
-  - Others: 55 files
-✓ Found 12 set(s) of duplicate files moved to Duplicates folder
-```
-
-**Edge Cases Handled:**
-- Empty folders: Displays "No files to organize" message
-- Invalid paths: Shows clear error message with validation
-- Permission errors: Skips files with access denied, continues processing
-- Unreadable files: Skips during hash calculation, no crash
-- Large monorepos: Excludes node_modules, .git, and build folders automatically
-
 ---
 
-### `run-tasks` - Batch Task Runner
+### `run-tasks` — Batch Task Runner
 
-Execute shell commands from a JSON configuration file, sequentially or in parallel. Supports task-specific working directories and comprehensive error handling.
+Execute shell commands from JSON config with parallel support.
 
 ```bash
 npx forgestack-os-cli run-tasks <config-path> [options]
 ```
 
-**Options:**
-- `--parallel` - Run tasks concurrently instead of sequentially (default: false)
-- `--stop-on-error` - Stop execution on first task failure (default: true)
+<table>
+<tr><th>Option</th><th>Description</th></tr>
+<tr><td><code>--parallel</code></td><td>Run tasks concurrently</td></tr>
+<tr><td><code>--stop-on-error</code></td><td>Stop on first failure (default: true)</td></tr>
+</table>
 
-**Config File Format (tasks.json):**
+**Config Format (tasks.json):**
 
 ```json
 {
   "tasks": [
     {
-      "name": "Build",
+      "name": "Build Frontend",
       "command": "npm run build",
-      "cwd": "./"
+      "cwd": "./frontend"
     },
-    {
-      "name": "Test",
-      "command": "npm test",
-      "cwd": "./"
-    }
+    { "name": "Build Backend", "command": "npm run build", "cwd": "./backend" },
+    { "name": "Run Tests", "command": "npm test" },
+    { "name": "Deploy", "command": "npm run deploy" }
   ],
   "parallel": false,
   "stopOnError": true
 }
 ```
 
-**Features:**
-- ✅ Cross-platform shell execution (Windows CMD, Unix bash)
-- ✅ Task-specific working directory support
-- ✅ Sequential or parallel execution modes
-- ✅ Configurable failure handling
-- ✅ Comprehensive error reporting
-- ✅ Interactive mode with default config file detection
-- ✅ Proper exit codes for CI/CD integration
-
-**Examples:**
+**Example:**
 
 ```bash
-# Run tasks sequentially (stops on first error)
-npx forgestack-os-cli run-tasks ./tasks.json
+# Run sequentially
+npx forgestack-os-cli run-tasks ./build-pipeline.json
 
-# Run tasks in parallel
-npx forgestack-os-cli run-tasks ./tasks.json --parallel
+# Run in parallel
+npx forgestack-os-cli run-tasks ./build-pipeline.json --parallel
 
 # Continue on errors
 npx forgestack-os-cli run-tasks ./tasks.json --stop-on-error false
-
-# Interactive mode (looks for ./tasks.json automatically)
-npx forgestack-os-cli run-tasks
 ```
 
-**Task Properties:**
-- `name` (required) - Display name for the task (for logging)
-- `command` (required) - Shell command to execute
-- `cwd` (optional) - Working directory for command execution (must exist)
+---
 
-**Example: Monorepo Build Pipeline**
+## 📚 Examples
 
-```json
-{
-  "tasks": [
-    {
-      "name": "Clean Build Artifacts",
-      "command": "rm -rf dist"
-    },
-    {
-      "name": "Build Frontend",
-      "command": "npm run build",
-      "cwd": "./packages/frontend"
-    },
-    {
-      "name": "Build Backend",
-      "command": "npm run build",
-      "cwd": "./packages/backend"
-    },
-    {
-      "name": "Run Tests",
-      "command": "npm test",
-      "cwd": "./packages/backend"
-    },
-    {
-      "name": "Generate Docs",
-      "command": "npm run docs"
-    }
-  ],
-  "parallel": false,
-  "stopOnError": true
-}
-```
+### Interactive Mode (Recommended)
 
-**Output Example:**
+```bash
+npx forgestack-os-cli create my-saas
+# Answer prompts to configure your perfect stack
 ```
-⏳ Running tasks sequentially...
-✓ Task 1/5: Clean Build Artifacts completed
-✓ Task 2/5: Build Frontend completed
-✓ Task 3/5: Build Backend completed
-✓ Task 4/5: Run Tests completed
-✓ Task 5/5: Generate Docs completed
-
-✓ All 5 tasks completed successfully
+
+### Using Presets
+
+```bash
+# Enterprise: Next.js + NestJS + Clerk + PostgreSQL
+npx forgestack-os-cli create my-enterprise --preset next-nest-clerk-pg
+
+# Startup: React + Express + JWT + MongoDB
+npx forgestack-os-cli create my-startup --preset react-express-jwt-mongo
+
+# Modern: Next.js + Fastify + Supabase + tRPC
+npx forgestack-os-cli create my-modern --preset next-fastify-supabase-trpc
 ```
 
-**Error Handling:**
-- **Invalid config path**: Shows clear error, no crash
-- **Malformed JSON**: Displays JSON parsing error
-- **Missing command**: Validates all tasks have required fields
-- **Invalid working directory**: Shows warning, continues with project root
-- **Task execution fails**: Respects `stopOnError` flag
-- **Cross-platform compatibility**: Automatically handles Windows vs Unix paths
+### Using Flags
 
----
+```bash
+# RESTful API with PostgreSQL
+npx forgestack-os-cli create my-api \
+  --frontend react-vite \
+  --backend express \
+  --auth jwt \
+  --database postgresql \
+  --api rest \
+  --docker
 
-## Features
+# GraphQL with MongoDB
+npx forgestack-os-cli create my-graphql \
+  --frontend vue-vite \
+  --backend nestjs \
+  --auth firebase \
+  --database mongodb \
+  --api graphql
 
-### Project Generation
-- **150+ Stack Combinations** - Frontend (React, Next.js, Vue, Svelte) × Backend (Express, Fastify, NestJS, Bun, Go) × Auth × Database × API Style
-- **Multi-tenancy Ready** - Scaffolding support for SaaS applications
-- **Docker Compose** - Complete Docker setup with frontend and backend services
-- **Environment Templates** - Pre-configured `.env.example` files
-- **API Documentation** - Swagger/OpenAPI docs for REST APIs
-- **TypeScript First** - Full TypeScript support across all generated code
-- **Production Ready** - Best practices, security headers, error handling
+# Multi-tenant SaaS
+npx forgestack-os-cli create my-saas \
+  --preset next-nest-clerk-pg \
+  --multi-tenant \
+  --docker
+```
 
-### Utility Commands
-- **File Organization** (`organize`) - Sort files by type or date, with MD5-based duplicate detection and automatic system folder exclusion
-- **Batch Task Runner** (`run-tasks`) - Execute complex workflows with sequential or parallel task execution, cross-platform compatibility, and comprehensive error handling
+### JSON Stack Config
 
-## Generated Project Structure
+```bash
+npx forgestack-os-cli create my-custom --stack '{
+  "frontend": "nextjs",
+  "backend": "fastify",
+  "auth": "supabase",
+  "database": "postgresql",
+  "apiStyle": "trpc",
+  "docker": true,
+  "multiTenant": true
+}'
+```
+
+---
+
+## 📁 Generated Project Structure
 
 ```
 my-app/
-├── frontend/              # React+Vite, Next.js, Vue, or SvelteKit
-│   ├── src/
-│   ├── public/
-│   ├── package.json
-│   ├── tsconfig.json
-│   └── vite.config.ts (or next.config.js)
+├── 📁 frontend/              # React/Next.js/Vue/Svelte
+│   ├── 📁 src/
+│   ├── 📄 package.json
+│   ├── 📄 tsconfig.json
+│   └── 📄 vite.config.ts
 │
-├── backend/               # Express, Fastify, NestJS, Bun+Elysia, or Go
-│   ├── src/
-│   ├── dist/
-│   ├── package.json
-│   ├── tsconfig.json
-│   └── .env.example
+├── 📁 backend/               # Express/Fastify/NestJS/Bun
+│   ├── 📁 src/
+│   │   ├── 📁 auth/          # Authentication module
+│   │   ├── 📁 users/         # User management
+│   │   └── 📄 main.ts
+│   ├── 📄 package.json
+│   ├── 📄 tsconfig.json
+│   └── 📄 .env.example
 │
-├── docker/                # Optional - if --docker enabled
-│   ├── docker-compose.yml
-│   ├── frontend.Dockerfile
-│   └── backend.Dockerfile
+├── 📁 docker/                # If --docker enabled
+│   ├── 📄 docker-compose.yml
+│   ├── 📄 frontend.Dockerfile
+│   └── 📄 backend.Dockerfile
 │
-├── .env.example           # Environment variables template
-├── package.json           # Workspace configuration (monorepo)
-├── README.md              # Per-project setup guide
-└── .gitignore
+├── 📄 .env.example           # Environment template
+├── 📄 package.json           # Monorepo workspace
+└── 📄 README.md              # Project-specific docs
 ```
 
-## Troubleshooting
+---
+
+## ❓ Troubleshooting
 
-### "command not found: forgestack-os-cli"
+<details>
+<summary><strong>"command not found: forgestack-os-cli"</strong></summary>
 
-**Using npx?** Make sure you use the full package name:
+Using npx? Use the full package name:
 
 ```bash
 npx forgestack-os-cli create my-app
 ```
 
-**Installed globally?** Try:
+Installed globally? Check your PATH includes npm's bin directory.
 
-1. Verify npm global bin is in PATH: `echo $PATH` (Unix) or `$env:Path` (Windows)
-2. Reinstall: `npm install -g forgestack-os-cli@latest`
-3. Check Node.js version: `node --version` (requires 18+)
+</details>
 
-### "404 Not Found - forgestack"
+<details>
+<summary><strong>"404 Not Found - forgestack"</strong></summary>
 
-The package name is **`forgestack-os-cli`**, not `forgestack`:
+The package name is `forgestack-os-cli`, not `forgestack`:
 
 ```bash
 # ✅ Correct
@@ -445,9 +428,12 @@ npx forgestack-os-cli create my-app
 npx forgestack create my-app
 ```
 
-### "Unknown command"
+</details>
 
-Ensure you're using `create`, not `init`:
+<details>
+<summary><strong>"Unknown command"</strong></summary>
+
+Use `create`, not `init`:
 
 ```bash
 # ✅ Correct
@@ -457,29 +443,69 @@ npx forgestack-os-cli create my-app
 npx forgestack-os-cli init my-app
 ```
 
-### Preset not found
+</details>
+
+<details>
+<summary><strong>"Preset not found"</strong></summary>
 
-Available presets:
+Available presets (case-sensitive):
 
-- `next-nest-clerk-pg` - Next.js, NestJS, Clerk, PostgreSQL
-- `react-express-jwt-mongo` - React+Vite, Express, JWT, MongoDB
-- `next-fastify-supabase-trpc` - Next.js, Fastify, Supabase, tRPC
+- `next-nest-clerk-pg`
+- `react-express-jwt-mongo`
+- `next-fastify-supabase-trpc`
 
-Use exact preset names (case-sensitive).
+</details>
 
-### Node.js version error
+<details>
+<summary><strong>Node.js version error</strong></summary>
 
-ForgeStack requires Node.js 18 or higher:
+ForgeStack requires Node.js 18+:
 
 ```bash
-node --version  # Check your version
-nvm install 18  # Or use nvm/fnm to upgrade
+node --version  # Check version
+nvm install 18  # Upgrade with nvm
 ```
 
-## Author
+</details>
+
+---
+
+## 🔗 Links
 
-Built and maintained by **Sumit Chauhan** ([halloffame12](https://github.com/halloffame12)).
+- 📚 [Documentation](https://github.com/halloffame12/forgestack-os#readme)
+- 🐛 [Issues](https://github.com/halloffame12/forgestack-os/issues)
+- 💬 [Discussions](https://github.com/halloffame12/forgestack-os/discussions)
+- 📦 [npm Package](https://www.npmjs.com/package/forgestack-os-cli)
+
+---
+
+## 👨‍💻 Author
+
+<table>
+<tr>
+<td>
+<img src="https://github.com/halloffame12.png" width="60" style="border-radius: 50%;" alt="Sumit Chauhan" />
+</td>
+<td>
+<strong>Sumit Chauhan</strong><br/>
+<a href="https://github.com/halloffame12">GitHub</a> •
+<a href="https://www.linkedin.com/in/sumit-chauhan-a4ba98325/">LinkedIn</a>
+</td>
+</tr>
+</table>
+
+---
+
+## 📄 License
+
+MIT License — see [LICENSE](./LICENSE) for details.
+
+---
 
-## License
+<p align="center">
+  <strong>⭐ Star us on GitHub if this tool helped you!</strong>
+</p>
 
-MIT
+<p align="center">
+  <sub>Made with ❤️ by <a href="https://github.com/halloffame12">Sumit Chauhan</a></sub>
+</p>