@vanthaita/orca 0.1.26 → 0.1.28

package/README.md

@@ -28,7 +28,11 @@ It's not just a wrapper; it's a workflow engine designed for the era of AI-assis
 ## ✨ Features
 
 - **🧠 Intelligent Commits**: Analyzes your diffs and generates conventional commit messages automatically.
-- **🗺️ Strategic Planning**: Generates a `plan.json` for complex tasks, allowing you to review and edit the strategy before execution.
+- **🌊 Workflow Orchestration**: Manage feature branches and lifecycles with `orca flow`.
+- **📚 Stacked Branches**: handle complex dependencies with `orca stack`.
+- **🧹 History Tidying**: Clean up your commit history with interactive rebase and autosquash using `orca tidy`.
+- **🛡️ Safety Checks**: Prevent secret leaks and run preflight checks with `orca safe`.
+- **🗺️ Strategic Planning**: Generates a `plan.json` for complex tasks.
 - **🚀 Zero-Friction Releases**: Handles the entire publish flow—commits, pushes, and creates a PR with a generated summary in one command.
 - **🔒 Local-First Privacy**: Your code stays on your machine. Orca interacts with AI providers securely using your own API keys.
 - **⚡ Blazing Fast**: Built with Rust for instant startup times and high performance.
@@ -39,14 +43,19 @@ Choose your preferred installation method:
 
 ### npm (Cross-platform)
 
+**Recommended for global installation:**
+
 ```bash
-npm install -g orca
+npm install -g @vanthaita/orca
 ```
 
+> [!NOTE]
+> Installing globally (`-g` flag) makes the `orca` command available system-wide. If you've previously installed via MSI or other methods, see the [Installation Notes](#-installation-notes) section below.
+
 ### Bun (Cross-platform)
 
 ```bash
-bun install -g orca
+bun install -g @vanthaita/orca
 ```
 
 ### Homebrew (macOS/Linux)
@@ -76,16 +85,6 @@ curl -fsSL https://raw.githubusercontent.com/vanthaita/orca-releases/main/instal
 2. Run the installer.
 3. Open a new terminal and type `orca --help`.
 
-### Portable Archive
-
-Download the appropriate archive for your platform from [Releases](https://github.com/vanthaita/orca-releases/releases/latest):
-
-- **Windows**: `orca-x86_64-pc-windows-msvc.zip`
-- **macOS**: `orca-x86_64-apple-darwin.tar.gz`
-- **Linux**: `orca-x86_64-unknown-linux-gnu.tar.gz`
-
-Extract and add to your system PATH.
-
 ### From Source
 
 Requirements: [Rust](https://rustup.rs/) (stable)
@@ -99,12 +98,67 @@ cd Orca/cli
 cargo install --path .
 ```
 
+## 📝 Installation Notes
+
+### Choosing the Right Installation Method
+
+- **Windows users**: Use the [MSI Installer](#windows-msi-installer) for the best experience. It handles PATH configuration automatically.
+- **npm/bun users**: Use the `-g` (global) flag to install system-wide. This makes `orca` available in any directory.
+- **Homebrew/winget users**: These package managers handle global installation automatically.
+
+### NPM Installation Tips
+
+> [!IMPORTANT]
+> **If you've installed via MSI or another method**, installing via npm may cause conflicts. Choose one installation method and stick with it.
+
+**Prevent automatic updates:**
+
+By default, npm may update packages automatically depending on your configuration. To lock to a specific version:
+
+```bash
+# Install a specific version
+npm install -g @vanthaita/orca@0.1.27
+
+# Check your installed version
+orca --version
+```
+
+**Troubleshooting npm installation:**
+
+```bash
+# If the command is not found after installation:
+which orca  # macOS/Linux
+where orca  # Windows
+
+# Reinstall if needed:
+npm uninstall -g @vanthaita/orca
+npm install -g @vanthaita/orca
+```
+
+### MSI and NPM Conflicts
+
+> [!WARNING]
+> If you installed Orca using the **Windows MSI installer**, do not install it again via npm. The MSI installer places the binary in your system PATH, and npm cannot update or manage it.
+
+**If you need to switch from MSI to npm:**
+
+1. Uninstall Orca via Windows Settings → Apps → Orca
+2. Then install via npm: `npm install -g @vanthaita/orca`
+
+**To update an MSI installation:**
+
+Download and run the latest MSI installer from [Releases](https://github.com/vanthaita/orca-releases/releases/latest).
+
 ## 🛠️ Usage
 
 ### 1. Setup
-Configure your preferred AI provider and API keys.
+Configure your preferred AI provider (Gemini, OpenAI, etc.) and API keys.
 
 ```bash
+# Setup with Gemini (default)
+orca setup --provider gemini --api-key YOUR_API_KEY
+
+# Setup with OpenAI
 orca setup --provider openai --api-key sk-...
 ```
 
@@ -116,20 +170,42 @@ Stage changes and generate a commit message in one go.
 orca commit
 ```
 
-### 3. Advanced Planning
+### 3. Workflow Management
+Start and finish features with ease.
+
+```bash
+# Start a new feature
+orca flow start --type feat --name user-auth
+
+# ... do work ...
+
+# Finish the feature (push and create PR)
+orca flow finish --push --pr
+```
+
+### 4. Stacked Branches
+Manage dependent branches without the headache.
+
+```bash
+# Create a child branch
+orca stack start my-child-branch
+
+# Rebase the stack if the parent moves
+orca stack rebase
+```
+
+### 5. Advanced Planning
 For complex features, generate a plan first.
 
 ```bash
-# Generate a plan based on current changes or a prompt
+# Generate a plan
 orca plan --out plan.json
 
-# ... Edit plan.json manually if needed ...
-
 # Execute the plan
 orca apply --file plan.json
 ```
 
-### 4. Publishing
+### 6. Publishing
 Ship your changes to GitHub without leaving the terminal.
 
 ```bash
@@ -139,16 +215,23 @@ orca publish --branch feat/my-new-feature
 
 ## ⌨️ Commands
 
-| Command | Description |
-|---------|-------------|
-| `orca commit` | Analyze changes and create a commit. |
-| `orca plan` | Generate a detailed execution plan. |
-| `orca apply` | Execute a plan file. |
-| `orca publish` | Commit, push, and create a PR. |
-| `orca setup` | Configure AI providers and settings. |
-| `orca login` | Authenticate with Orca Cloud. |
-| `orca doctor` | Check environment health. |
-| `orca update` | Update to the latest version. |
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `orca commit` | | Analyze changes and create a commit. |
+| `orca flow` | `fl` | Manage feature/fix workflows (`start`, `finish`). |
+| `orca stack` | `sk` | Manage stacked branches (`start`, `list`, `rebase`, `publish`). |
+| `orca tidy` | `td` | Clean up history (`rebase`, `squash`, `fixup`, `amend`). |
+| `orca conflict` | `cf` | Resolve conflicts (`status`, `guide`, `continue`, `abort`). |
+| `orca release` | `rl` | Manage releases (`tag`, `notes`, `create`). |
+| `orca safe` | | Safety checks (`scan`, `preflight`). |
+| `orca git` | `g` | Enhanced git wrappers (`status`, `log`, `sync`). |
+| `orca branch` | `br` | Branch management (`current`, `list`, `new`, `publish`). |
+| `orca plan` | | Generate a detailed execution plan. |
+| `orca apply` | | Execute a plan file. |
+| `orca publish` | | Commit, push, and create a PR. |
+| `orca setup` | | Configure AI providers and settings. |
+| `orca update` | | Update to the latest version. |
+| `orca doctor` | | Check environment health. |
 
 ## 🤝 Contributing
 

package/package.json

@@ -1,7 +1,8 @@
 {
     "name": "@vanthaita/orca",
-    "version": "0.1.26",
-    "description": "AI-powered Git Workflow automation for modern developers",
+    "version": "0.1.28",
+    "description": "AI-powered Git workflow CLI for modern developers. Intelligent commits, workflow orchestration, and zero-friction releases.",
+    "preferGlobal": true,
     "scripts": {
         "postinstall": "node install.js"
     },