From 415022d1dc8adb85ddb52cee802bdd26a4e961d9 Mon Sep 17 00:00:00 2001
From: To Nguyen <hanh.tonguyen@visssoft.com>
Date: Thu, 19 Mar 2026 01:27:39 +0700
Subject: [PATCH] Update README.md with full CLI reference and
 install-from-source guide

- Add CLI Reference section with all commands (init, validate, list, --version, --help)
- Document new flags: --dry-run, --backup, --force with short forms
- Add install-from-source instructions via git clone + npm link
- Update verify step to use 'antigravity-superpowers validate' instead of shell script
- Add visssoft git URL for clone instructions
- Update Development section with test count and smoke check details

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 82 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 7e7e2a3..096cdea 100644
--- a/README.md
+++ b/README.md
@@ -77,7 +77,30 @@ npm install -g antigravity-superpowers
 antigravity-superpowers init
 ```
 
-### Options
+Or install from source (Git):
+
+```bash
+git clone https://git.visssoft.com/hanh.tonguyen/antigravity-superpowers.git
+cd antigravity-superpowers
+npm link
+
+# Now use it anywhere
+antigravity-superpowers init
+```
+
+After init, verify everything is wired up:
+
+```bash
+antigravity-superpowers validate
+```
+
+---
+
+## CLI Reference
+
+### `antigravity-superpowers init [dir] [options]`
+
+Initialize the `.agent` profile in a project directory.
 
 ```bash
 # Initialize in current directory
@@ -86,14 +109,56 @@ antigravity-superpowers init
 # Initialize in a specific project
 antigravity-superpowers init /path/to/project
 
+# Preview files that would be copied (no changes made)
+antigravity-superpowers init --dry-run
+
 # Replace an existing .agent profile
 antigravity-superpowers init --force
+
+# Backup existing .agent before replacing
+antigravity-superpowers init --force --backup
 ```
 
-After init, verify everything is wired up:
+| Option | Short | Description |
+| --- | --- | --- |
+| `--force` | `-f` | Overwrite existing `.agent` directory |
+| `--backup` | `-b` | Backup existing `.agent` to `.agent-backup-<timestamp>` before overwrite (use with `--force`) |
+| `--dry-run` | `-n` | Preview the file list without copying anything |
+
+### `antigravity-superpowers validate [dir]`
+
+Run profile validation checks on an initialized project. Verifies file presence, skill completeness, frontmatter validity, legacy pattern absence, and AGENTS mapping contract.
 
 ```bash
-bash .agent/tests/run-tests.sh
+# Validate current directory
+antigravity-superpowers validate
+
+# Validate a specific project
+antigravity-superpowers validate /path/to/project
+```
+
+### `antigravity-superpowers list`
+
+List all 13 bundled skills with their names and descriptions.
+
+```bash
+antigravity-superpowers list
+```
+
+### `antigravity-superpowers --version`
+
+Show the current CLI version.
+
+```bash
+antigravity-superpowers --version   # or -v
+```
+
+### `antigravity-superpowers --help`
+
+Show usage information.
+
+```bash
+antigravity-superpowers --help      # or -h
 ```
 
 ---
@@ -191,7 +256,7 @@ When making changes, run the validation suite to make sure everything still chec
 
 ```bash
 npm test
-bash .agent/tests/run-tests.sh
+antigravity-superpowers validate
 ```
 
 ---
@@ -199,14 +264,24 @@ bash .agent/tests/run-tests.sh
 ## Development
 
 ```bash
-npm test              # Run tests
-npm run smoke:pack    # Verify package contents
+git clone https://git.visssoft.com/hanh.tonguyen/antigravity-superpowers.git
+cd antigravity-superpowers
+
+npm test              # Run 20 tests (cli, init, validate)
+npm run smoke:pack    # Verify package contents (31 required files)
+```
+
+### Install from Source
+
+```bash
+npm link              # Symlink CLI globally
+antigravity-superpowers --version
 ```
 
 ### Publishing
 
 ```bash
-npm version patch
+npm version patch     # or minor/major
 npm publish
 ```