stillrivercode · adslaton · Jul 17, 2025 · Jul 17, 2025 · Jul 17, 2025
diff --git a/README.md b/README.md
@@ -15,57 +15,74 @@ A curated collection of action-oriented keywords organized in a modular structur
 - 🔧 **GitHub integration** with automated workflows and validation
 - 🛡️ **Quality assurance** with security scanning and emergency controls
 
-## 📦 Installation & Usage
+## 📦 Installation & Updates
 
-### 🤖 AI Assistant Configuration
-
-When you run the installer, a file named `AI.md` is copied to your installation directory (e.g., `docs/AI.md`). This file contains shared instructions and context for any AI assistant you use, ensuring it understands the project's conventions and the "Information Dense Keywords" command set.
-
-You are encouraged to customize this file with project-specific details.
-
-### For Individual Users
-
-#### Option 1: NPX Install (Recommended)
+### Individual Users
 
 ```bash
 # Install dictionary to docs/ directory
 npx @stillrivercode/information-dense-keywords
 
 # Or install to custom directory
 npx @stillrivercode/information-dense-keywords /path/to/custom/docs
+
+# Show help
+npx @stillrivercode/information-dense-keywords --help
 ```
 
-#### Option 2: Online Reference
+### Teams & Organizations
 
-1. **View the dictionary on GitHub**: Visit [github.com/stillriver/idk](https://github.com/stillriver/idk)
-2. **Browse command definitions**: Navigate through the dictionary structure to find commands
-3. **Copy command syntax**: Use the exact command text when prompting your AI assistant
-4. **Example usage**: Tell your AI: `analyze this authentication system for security vulnerabilities`
+Add to your project's `package.json`:
 
-### For Teams & Organizations
+```json
+{
+  "dependencies": {
+    "@stillrivercode/information-dense-keywords": "^1.0.0"
+  },
+  "scripts": {
+    "idk:install": "npx @stillrivercode/information-dense-keywords",
+    "idk:update": "npm update @stillrivercode/information-dense-keywords"
+  }
+}
+```
 
-#### Fork & Customize
+Then run:
 
 ```bash
-# Fork the repository on GitHub
-# Clone your fork
-git clone https://github.com/YOUR_USERNAME/idk.git
-cd idk
-
-# Add your custom commands
-mkdir dictionary/custom
-# Add your team-specific commands to dictionary/custom/
-# Update information-dense-keywords.md with links to your custom commands
+npm install
+npm run idk:install
 ```
 
-### For AI Assistant Developers
+### AI Assistant Configuration
+
+When you run the installer, a file named `AI.md` is copied to your installation directory (e.g., `docs/AI.md`). This file contains shared instructions and context for any AI assistant you use, ensuring it understands the project's conventions and the "Information Dense Keywords" command set.
 
-#### Integration Instructions
+You are encouraged to customize this file with project-specific details.
 
-1. **Read the AI guidance**: [AI.md](AI.md), [CLAUDE.md](CLAUDE.md), [GEMINI.md](GEMINI.md)
-2. **Implement command recognition** using the definitions in `dictionary/`
-3. **Follow output formats** specified in each command definition
-4. **Support command chaining** as documented in the main index
+## 📋 Quick Reference
+
+| Command          | Purpose                           | Category           |
+|------------------|-----------------------------------|--------------------|
+| **SELECT**       | Information retrieval             | Core               |
+| **CREATE**       | Generate new assets               | Core               |
+| **DELETE**       | Remove assets                     | Core               |
+| **FIX**          | Debug and correct                 | Core               |
+| **analyze this** | Code analysis                     | Development        |
+| **debug this**   | Issue investigation               | Development        |
+| **optimize this**| Performance improvement           | Development        |
+| **document this**| Create documentation              | Documentation      |
+| **explain this** | Provide explanations              | Documentation      |
+| **research this**| Investigate topics                | Documentation      |
+| **test this**    | Generate tests                    | Quality Assurance  |
+| **review this**  | Code review                       | Quality Assurance  |
+| **plan this**    | Implementation planning           | Workflow           |
+| **spec this**    | Technical specifications          | Workflow           |
+| **roadmap**      | Strategic development roadmaps    | Workflow           |
+| **gh**           | GitHub operations                 | Git                |
+| **commit**       | Git commits                       | Git                |
+| **push**         | Push to remote                    | Git                |
+| **pr**           | Pull requests                     | Git                |
+| **comment**      | GitHub comments                   | Git                |
 
 ## 🚀 Quick Start Examples
 

diff --git a/install.sh b/install.sh
@@ -14,8 +14,66 @@ NC='\033[0m' # No Color
 # Default installation directory
 DEFAULT_INSTALL_DIR="./docs"
 
+# Function to show help
+show_help() {
+    echo -e "${GREEN}Information Dense Keywords Dictionary Installer${NC}"
+    echo "================================================"
+    echo ""
+    echo "USAGE:"
+    echo "  $0 [DIRECTORY]"
+    echo "  $0 -h|--help"
+    echo ""
+    echo "DESCRIPTION:"
+    echo "  Installs the Information Dense Keywords Dictionary to a specified directory."
+    echo "  The dictionary includes the main reference file, command definitions, and AI instructions."
+    echo ""
+    echo "ARGUMENTS:"
+    echo "  DIRECTORY    Installation directory (default: $DEFAULT_INSTALL_DIR)"
+    echo ""
+    echo "OPTIONS:"
+    echo "  -h, --help   Show this help message and exit"
+    echo ""
+    echo "EXAMPLES:"
+    echo "  $0              # Install to default location (./docs)"
+    echo "  $0 ~/my-docs    # Install to custom directory"
+    echo "  $0 --help       # Show this help message"
+    echo ""
+    echo "INSTALLED FILES:"
+    echo "  - DIRECTORY/information-dense-keywords.md  # Main dictionary reference"
+    echo "  - DIRECTORY/dictionary/                   # Command definitions"
+    echo "  - DIRECTORY/AI.md                         # AI assistant instructions"
+    echo ""
+    echo "NOTES:"
+    echo "  - Installation in system directories (/etc, /usr, etc.) is not allowed"
+    echo "  - Existing files will be preserved and merged where appropriate"
+    echo "  - AI.md will only be copied if it doesn't already exist in the target directory"
+}
+
 # Parse command line arguments
-INSTALL_DIR="${1:-$DEFAULT_INSTALL_DIR}"
+INSTALL_DIR=""
+for arg in "$@"; do
+    case "$arg" in
+        -h|--help)
+            show_help
+            exit 0
+            ;;
+        *)
+            # Assume the first non-flag argument is the directory
+            if [[ -z "$INSTALL_DIR" ]]; then
+                # Check that it doesn't look like a flag a user might have typo'd
+                if [[ "$arg" =~ ^- ]]; then
+                    echo -e "${RED}Error: Unknown option '$arg'${NC}"
+                    show_help
+                    exit 1
+                fi
+                INSTALL_DIR="$arg"
+            fi
+            ;;
+    esac
+done
+
+# If no directory was provided, use the default
+INSTALL_DIR="${INSTALL_DIR:-$DEFAULT_INSTALL_DIR}"
 
 # Prevent installation in sensitive system directories
 if [[ "$INSTALL_DIR" == "/" || "$INSTALL_DIR" == "/etc" || "$INSTALL_DIR" == "/usr"* || "$INSTALL_DIR" == "/var"* || "$INSTALL_DIR" == "/bin"* || "$INSTALL_DIR" == "/sbin"* ]]; then