feat: add help command to installer and restructure README

[adslaton]

Summary

• Add comprehensive help command to install.sh with -h/--help flags
• Restructure README.md to lead with Installation & Updates section
• Move Quick Reference before Quick Start for better user flow

Changes Made

• install.sh: Added show_help() function with comprehensive usage information
• README.md: Restructured sections to prioritize installation and quick reference
• Documentation: Include new --help flag in installation examples
• Team Integration: Improved NPM scripts for idk:install and idk:update

Test plan

• Test help command with ./install.sh --help
• Test help command with ./install.sh -h
• Verify README structure flows logically
• Confirm all pre-commit hooks pass

🤖 Generated with Claude Code

[github-actions]

🔒 Security Scan Results

✅ npm audit - Dependency Security

No vulnerable dependencies found.

⚠️ audit-ci Security Check

No results file generated.

⚠️ ESLint Security Analysis

No results file generated.

---

✅ All security scans passed! No issues found.

[github-actions]

🤖 AI Review

---

This review was automatically generated by google/gemini-2.5-pro via OpenRouter. Please consider it as supplementary feedback alongside human review.

[github-actions]

🤖 AI Review

Of course! Here is a detailed review of the pull request.

---

Pull Request Review

PR Title: Add comprehensive help command to install.sh and restructure README

Summary of Changes

This pull request introduces two main improvements:

1. install.sh Enhancement: A show_help function has been added to the installation script, which is triggered by -h or --help flags. This provides users with clear instructions on usage, arguments, and options directly from the command line.
2. README.md Restructuring: The main documentation has been reorganized to prioritize installation instructions and provide a quick reference table of commands upfront. This significantly improves the onboarding experience for new users.

---

Strengths of the Implementation

1. Excellent Documentation Overhaul: The restructuring of README.md is a fantastic change. Placing "Installation & Updates" at the top, followed by a "Quick Reference" table, makes the project much more accessible and user-friendly. This is a great example of thinking from the user's perspective.
2. Clear and Comprehensive Help Message: The new show_help() function in install.sh is well-written, clear, and provides all the necessary information a user would need. The use of color-coding and structured sections (USAGE, DESCRIPTION, EXAMPLES) is a best practice for CLI help text.
3. Good Shell Scripting Practices: The script uses variables for color codes (GREEN, NC), which improves readability and maintainability. It also correctly uses exit 0 after displaying the help message.
4. Team-Focused Improvements: Adding the idk:install and idk:update scripts to the package.json example is a thoughtful addition that makes integration for teams much smoother.

---

Issues or Concerns

1. Code Quality and Best Practices / Potential Bugs

The argument parsing in install.sh is a bit too simple and can lead to unexpected behavior.

• Issue: The script only checks if the first argument ($1) is a help flag. It does not handle cases where the help flag appears after another argument.
• Example: Running ./install.sh /some/path --help would not show the help message. Instead, it would try to install the dictionary into the /some/path directory, completely ignoring the --help flag.
• Impact: This violates the principle of least surprise. Users familiar with standard CLI tools expect flags like --help to work regardless of their position.

2. Security Concerns

• No security concerns were introduced with this change. The existing safeguard that prevents installation in root system directories is still in place and is a good security measure.

3. Performance Implications

• There are no performance implications. The changes only affect the one-time execution of an installation script.

4. Test Coverage

• The provided test plan is good for the happy paths (./install.sh -h and ./install.sh --help).
• However, it misses the edge case identified above (./install.sh /some/path --help), which would have revealed the bug in the argument parsing logic.

5. Documentation Updates Needed

• The documentation changes in the PR are excellent. No further updates are needed.

---

Suggestions for Improvement

To address the argument parsing issue, I recommend a more robust approach that iterates through all arguments to check for the help flag. A for loop is simple and effective for this case.

Suggestion: Replace the current argument parsing block with the following logic in install.sh:

# --- Current Code ---
# Parse command line arguments
# if [[ "$1" == "-h" || "$1" == "--help" ]]; then
#     show_help
#     exit 0
# fi
#
# INSTALL_DIR="${1:-$DEFAULT_INSTALL_DIR}"

# --- Suggested Improvement ---
# Parse command line arguments
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}"

Why this is better:

• Robustness: It correctly handles --help regardless of its position among the arguments.
• Extensibility: This case statement structure makes it easy to add more flags/options in the future.
• Error Handling: It adds basic handling for unknown options (arguments starting with -), improving the user experience for typos.

---

Overall Recommendation

Request Changes

This is a high-quality pull request that makes significant usability improvements. The documentation changes are perfect. The only thing holding it back from immediate approval is the brittle argument parsing in install.sh.

With the suggested improvement to the argument parsing logic, this PR will be excellent. Great work

---

This review was automatically generated by google/gemini-2.5-pro via OpenRouter. Please consider it as supplementary feedback alongside human review.

[adslaton]

🔧 AI Review Feedback Addressed

Thanks for the detailed review! I've implemented the suggested improvements to the argument parsing logic in install.sh.

Changes Made

✅ Robust Argument Parsing

• Replaced simple $1 check with a case statement loop
• Help flags (-h/--help) now work in any position among arguments
• Example: ./install.sh /some/path --help now correctly shows help

✅ Error Handling

• Added detection for unknown options (flags starting with -)
• Shows clear error message and help when unknown flags are encountered
• Example: ./install.sh --unknown-flag shows error and help

✅ Improved Structure

• Used extensible case statement for easy addition of future flags
• Better separation of concerns in argument processing

Testing Results

# All these now work correctly:
./install.sh --help                    # ✅ Shows help
./install.sh -h                        # ✅ Shows help  
./install.sh /tmp/test --help           # ✅ Shows help (was broken before)
./install.sh --unknown-flag            # ✅ Shows error + help

The implementation follows the exact pattern suggested in the review. Ready for re-review! 🚀

[github-actions]

🤖 AI Review

Of course. Here is a comprehensive review of the pull request.

---

Pull Request Review

PR Title: Add help command and restructure docs

This is an excellent pull request that significantly improves the usability and developer experience of the project. The changes are well-thought-out, addressing both the command-line interface and the primary documentation.

---

Summary of Changes

The pull request introduces two main improvements:

1. install.sh Enhancement: The installation script is updated to include a comprehensive help message accessible via -h and --help flags. The argument parsing logic has been made more robust to handle these flags and prevent misinterpretation of arguments.
2. README.md Restructuring: The main README.md file has been reorganized to prioritize installation information and provide a "Quick Reference" table. This makes it easier for new users to get started and for existing users to find commands quickly. The instructions for teams have also been made more concrete with NPM script examples.

---

Strengths of the Implementation

• User-Centric Documentation: The README restructure prioritizes what a user needs first: how to install the software. Moving the Quick Reference table above the Quick Start examples is also a logical flow, allowing users to see what's available before seeing it in action.
• Robust Scripting: The install.sh script now uses a proper argument parsing loop. This is a major improvement over the simple "${1:-...}" assignment, as it correctly handles flags regardless of their position and prevents the script from trying to create a directory named -h.
• Self-Documenting Code: Adding a show_help function is a best practice. The help text is clear, well-formatted, and provides all the necessary information for a user to understand and use the script correctly.
• Improved Team Onboarding: The new "Teams & Organizations" section with package.json snippets is far more practical and actionable than the previous "Fork & Customize" instructions. It provides a clear path for integrating the dictionary into an existing project workflow.

---

Analysis by Focus Area

1. Code Quality and Best Practices

• install.sh:
  • Good: The use of a for/case loop for argument parsing is standard and robust.
  • Good: The defensive check if [[ "$arg" =~ ^- ]] to catch unknown options is excellent and prevents common user errors.
  • Good: The script is more readable with the show_help function separated from the main logic.
  • Suggestion: For maximum portability, you could consider changing the shebang from #!/bin/bash to #!/usr/bin/env bash. This is a minor point, as /bin/bash is available on almost all systems where this would run.

2. Potential Bugs or Issues

I found one minor edge case in the install.sh script's argument parsing:

• Issue: If a user provides multiple non-flag arguments (e.g., ./install.sh dir1 dir2), the script will silently use the first one (dir1) and ignore the second (dir2). This isn't a critical bug, but it could lead to user confusion.

• Suggestion: You could make the script stricter by exiting with an error if more than one positional argument is provided.

  # Inside the *) case in the for loop
  if [[ -n "$INSTALL_DIR" ]]; then
      echo -e "${RED}Error: Too many arguments. Please specify only one installation directory.${NC}"
      show_help
      exit 1
  fi
  INSTALL_DIR="$arg"

3. Security Concerns

• No new security concerns are introduced.
• The existing safeguard preventing installation in sensitive system directories (/, /etc, /usr, etc.) is still in place and effective. This is a crucial check that has been correctly preserved.

4. Performance Implications

• There are no performance implications. The changes to install.sh are negligible in terms of execution time.

5. Test Coverage

• The test plan described in the PR is manual but appropriate for this type of change. It covers the primary success paths (-h, --help) and confirms the desired outcome.
• The plan correctly includes verifying the documentation's logical flow, which is a key part of this PR. The pre-commit hooks passing provides an automated check on code style and quality.

6. Documentation Updates Needed

• The PR itself is a documentation update. The changes are excellent.
• The install.sh script is now self-documenting via the --help flag.
• The README.md is significantly improved and requires no further changes based on this PR.

---

Overall Recommendation

This is a high-quality contribution that demonstrably improves the project. The changes are thoughtful, well-executed, and align with best practices for both shell scripting and documentation.

I Approve this pull request.

The suggestion to handle multiple arguments is minor and can be addressed in a future PR if desired. It does not prevent this PR from being merged. Great work

---

This review was automatically generated by google/gemini-2.5-pro via OpenRouter. Please consider it as supplementary feedback alongside human review.

[github-actions]

🎉 This PR is included in version 1.7.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀