KeywordLens v0.32.0 — Quick Start Guide
==================================================

KeywordLens is an AI-powered photo tagging plugin for Adobe Lightroom Classic.
It generates keywords, titles, and captions using vision AI models.

PREREQUISITES
  - Adobe Lightroom Classic (2022 or later)
  - Python 3.12 or later
  - An AI provider: Ollama (local), Azure OpenAI, Google Gemini, or LM Studio

INSTALLATION

  Option A: Automated Setup (recommended)
  ----------------------------------------
  Windows:  Double-click setup\setup.bat
            (or, advanced: powershell -ExecutionPolicy Bypass -File setup\setup.ps1)
  macOS:    bash setup/setup.sh
            (or, equivalently: chmod +x setup/setup.sh && ./setup/setup.sh)

    The setup script creates a Python virtual environment, installs
    dependencies, and prepares the backend for use. If Python 3.12+
    is missing, setup uses Homebrew on macOS or winget on Windows when
    available. If those package managers are missing, macOS can offer
    to install Homebrew; Windows opens the official App Installer /
    winget route and asks you to rerun setup afterward.

  Windows note (Mark-of-the-Web): Files downloaded with a browser are
  often flagged by Windows. If setup.bat refuses to run, or you see
  red SmartScreen warnings, right-click the downloaded ZIP first ->
  Properties -> tick "Unblock" -> Apply, THEN extract.

  macOS note (Gatekeeper / quarantine): If the setup script refuses
  to run, or Lightroom cannot add the plug-in folder, clear the
  quarantine attribute on the install directory once:

      xattr -dr com.apple.quarantine "/path/to/keywordlens"

  Option B: Docker
  -----------------
  cd server
  docker compose up -d

  Option C: Manual
  -----------------
  cd server
  python -m venv venv
  # Windows: venv\Scripts\activate
  # macOS:   source venv/bin/activate
  pip install -r requirements.txt
  cd src
  python main.py

ADDING THE PLUGIN TO LIGHTROOM
  This is a separate step from the setup script. The setup script
  only prepares the Python backend; you still have to register the
  plug-in folder with Lightroom manually.

  1. Open Lightroom Classic.
  2. Open the Plug-in Manager:
       Windows: File -> Plug-in Manager  (shortcut: Ctrl+Alt+Shift+,)
       macOS:   File -> Plug-in Manager  (shortcut: Cmd+Option+Shift+,)
  3. Click "Add" in the bottom-left of the Plug-in Manager window.
  4. Browse to your unzipped install directory and select the
     folder:
         plugin/keywordlens.lrdevplugin
     (Select the folder ITSELF -- do not open it and pick a file
     inside.)
  5. Confirm. The plug-in should appear in the left-hand list as
     "KeywordLens" with a green Enabled badge. The Setup Wizard
     will then guide you through provider configuration.

  Plug-in won't appear after Add (or shows red Error / Not loaded)?
    Windows: most often Mark-of-the-Web on the downloaded ZIP. Right-
      click the ZIP -> Properties -> Unblock -> Apply, then re-
      extract and try again.
    macOS: most often Gatekeeper quarantine. Run
      `xattr -dr com.apple.quarantine "/path/to/keywordlens"`
      once on the extracted folder, then re-add.
    Either OS: verify you selected the .lrdevplugin folder itself
      and that Info.lua exists inside it.

USING THE PLUGIN
  1. Select photos in your Library
  2. Go to File → Plug-in Extras → Analyze Photos with AI
  3. Review settings and click Analyze

UPGRADING AN EXISTING INSTALLATION
  The ZIP unpacks into a constant folder name (keywordlens/), so
  upgrades are an in-place file overwrite.

  1. Quit Lightroom (or at minimum Plug-in Manager → KeywordLens →
     Disable). This releases any locks on the .lrdevplugin folder.
  2. Extract the new ZIP into the SAME parent directory as your old
     install. Use the CLI for the smoothest result:

         macOS:    unzip -o ~/Downloads/keywordlens-v0.32.0.zip -d /path/to/parent/
         Windows:  Expand-Archive -Force -Path keywordlens-v0.32.0.zip -DestinationPath C:\path\to\parent\

     The flags `-o` (unzip) and `-Force` (Expand-Archive) overwrite
     existing files. Files NOT in the ZIP -- most importantly your
     server/.env with Azure / API credentials -- are left untouched.

     macOS Finder warning: do NOT click "Replace" when Finder offers
     to "replace keywordlens" -- that wipes the folder first, taking
     server/.env with it. Use the CLI command above, or click "Keep
     Both" and copy server/.env across manually.

  3. Reopen Lightroom (or Plug-in Manager → Enable). The plug-in
     reloads with the new code and a small "KeywordLens backend
     ready" bezel appears once the backend answers /health.

  4. **Translation changes only:** if release notes mention locale
     string changes, fully restart Lightroom. Lightroom Classic
     loads TranslatedStrings_*.txt once per process.

  Anything that lives OUTSIDE the install folder is automatically
  preserved across upgrades:
    - ~/.keywordlens/keywordlens.db (catalog + analysis state)
    - ~/.keywordlens/server.log
    - ~/.keywordlens/offline-packs/ (when configured there)
    - Lightroom preferences (provider choice, API keys, etc.)

INTERACTIVE PACK BUILDER
  Build offline location packs for GPS-aware tagging:
  1. Start the backend (auto-starts with Lightroom, or manually)
  2. Open http://localhost:8099/tools/pack-builder in your browser

DOCUMENTATION
  See docs/user-manual.md for the full user guide.
  See docs/installation-guide.md for detailed setup instructions.
