Clean deployment: add PDF user guide, drop desktop/dev-only files

.env.example

@@ -1,54 +0,0 @@
-# Copy this file to .env, or just configure everything from the app's
-# Setup page — the app writes these values to .env for you. Never commit .env.
-
-# --------------------------------------------------
-# Main LLM provider — "openai", "anthropic", "groq", or "gemini"
-# --------------------------------------------------
-LLM_PROVIDER=openai
-
-# OpenAI (used when LLM_PROVIDER=openai)
-# Suggested models: gpt-4.1, gpt-4.1-mini, gpt-4o, gpt-4o-mini  (4o/4.1 = vision)
-OPENAI_API_KEY=
-OPENAI_MODEL=gpt-4.1
-
-# Anthropic (used when LLM_PROVIDER=anthropic; leave blank otherwise)
-# Suggested models: claude-sonnet-4-6, claude-3-5-sonnet-latest, claude-3-5-haiku-latest
-ANTHROPIC_API_KEY=
-ANTHROPIC_MODEL=
-
-# Groq (used when LLM_PROVIDER=groq; leave blank otherwise). Text-only here.
-# Suggested models: llama-3.3-70b-versatile, llama-3.1-8b-instant, mixtral-8x7b-32768, gemma2-9b-it
-GROQ_API_KEY=
-GROQ_MODEL=llama-3.3-70b-versatile
-
-# Gemini (used when LLM_PROVIDER=gemini; leave blank otherwise)
-# Suggested models: gemini-1.5-pro, gemini-1.5-flash, gemini-2.0-flash, gemini-2.0-flash-lite
-GEMINI_API_KEY=
-GEMINI_MODEL=gemini-1.5-pro
-
-# Vision model for reading job screenshots. VISION_PROVIDER may be "openai",
-# "anthropic", "gemini", or "same_as_llm" (reuse LLM_PROVIDER when it supports
-# images). Groq is NOT a valid vision provider — it is text-only in this app.
-# VISION_MODEL must be a vision-capable model.
-# Suggested vision models — OpenAI: gpt-4o, gpt-4.1; Anthropic: claude-sonnet-4-6,
-# claude-3-5-sonnet-latest; Gemini: gemini-1.5-pro, gemini-1.5-flash, gemini-2.0-flash.
-VISION_PROVIDER=openai
-VISION_MODEL=gpt-4o
-
-# --------------------------------------------------
-# Safety / fallback controls — keep false for production-like behavior.
-# When false, the main UI hides provider/model labels, task names, and raw
-# API errors; only short, safe, actionable messages are shown.
-# --------------------------------------------------
-ALLOW_PROVIDER_FALLBACK=false
-ALLOW_LOCAL_PLACEHOLDERS=false
-SHOW_DEBUG_PANEL=false
-
-# --------------------------------------------------
-# Proposal context limits and logging. The full dossier is never sent; only
-# a small relevance-filtered subset is.
-# --------------------------------------------------
-MAX_PROPOSAL_CONTEXT_CHARS=15000
-MAX_PROPOSAL_EVIDENCE_POINTS=20
-PROPOSAL_MAX_OUTPUT_TOKENS=700
-LOG_RETENTION_DAYS=7

.gitignore

@@ -1,39 +0,0 @@
-.env
-.env.*
-!.env.example
-.env.tmp
-.venv
-venv/
-__pycache__/
-*.pyc
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-logs/
-*.db
-*.sqlite
-.DS_Store
-
-# Mac virtual environment — created on first run, machine-specific
-runtime_mac/
-
-# The bundled Python lives in runtime/ and IS committed, so a git download runs
-# directly (no separate staging step). Only the per-machine, first-run-generated
-# bits are kept out of git:
-runtime/Lib/
-runtime/Scripts/
-runtime/.deps_installed
-runtime/python-embed.zip
-
-# Packaging / build outputs
-build/
-dist/
-.venv-build/
-*.egg-info/
-
-# Claude Code local settings (machine-specific)
-.claude/settings.local.json
-
-# Personal sample dossier files (PII) — only the template is committed
-sample_dossier/*
-!sample_dossier/TEMPLATE_dossier.json

DEVELOPER.md

@@ -1,252 +0,0 @@
-# Developer & Packaging Guide
-
-Everything technical lives here. **End users need none of it** — they double-click
-`Start Upwork Proposal Strategist` (see [README.md](README.md)). This document
-covers how the browser-app design works, how to run from source, and how to
-build/distribute.
-
----
-
-## 1. How it works (architecture)
-
-The goal: a non-technical Windows user double-clicks **one** thing and the app
-opens in their **web browser**, with **nothing pre-installed** — no Python,
-conda, pip, PYTHONPATH, or env vars, ever.
-
-Python travels *inside* the folder — `runtime\` (the embeddable Python) is
-**committed to the repo**, so every checkout, "Download ZIP", and packaged zip
-already has it. The client never downloads an interpreter — only the app's
-libraries, from PyPI, on the first run.
-
-```
-Start Upwork Proposal Strategist.bat       ← user double-clicks (console = "running" light)
-  └─ scripts\run.bat                        ← sets UPS_PACKAGED=1, then…
-       ├─ scripts\ensure_runtime.bat        ← FIRST RUN ONLY:
-       │     1. (Python is already in runtime\ — bundled, not downloaded)
-       │     2. enable site-packages in python311._pth
-       │     3. install pip from the bundled get-pip.py
-       │     4. pip install -r requirements.txt   (from PyPI; internet)
-       │     5. write runtime\.deps_installed   ← success marker (LAST)
-       └─ runtime\python.exe desktop_app.py  ← runs in the FOREGROUND (this console)
-             ├─ picks a free 127.0.0.1 port; starts Streamlit headless, in-process
-             ├─ a daemon thread waits for /_stcore/health, then opens the browser
-             └─ closing the console window stops the server (one process; no orphan)
-```
-
-Key properties:
-
-- **Bundled interpreter, libraries on first run.** `runtime\python.exe` ships
-  inside the folder; `ensure_runtime.bat` only installs the Python libraries
-  (once). There is **no "download an interpreter from the web" step** — that
-  download-then-execute pattern is what antivirus/SmartScreen flags. The old
-  `pywebview` / `pythonnet` / WebView2 stack is gone: the UI is just the browser.
-- **Idempotent + self-healing setup.** `ensure_runtime.bat` writes its success
-  marker (`runtime\.deps_installed`) **only after every step succeeds**, so an
-  interrupted/failed first run leaves no marker and simply resumes on the next
-  launch. A completed setup is an instant no-op.
-- **Single process, clean shutdown.** `desktop_app.py` *is* the Streamlit server
-  (its stable CLI is driven in-process) and runs in the foreground. Closing the
-  console window stops it — nothing to taskkill, no orphaned `python.exe`.
-- **No PYTHONPATH.** The project is a proper installable package
-  (`pyproject.toml`), and the launcher (`desktop_app.py`) puts the project root
-  on `sys.path` before handing off to Streamlit.
-- **Writable state is outside the folder.** The API-key `.env` and logs live in
-  `%APPDATA%\UpworkProposalStrategist\`, so the install folder can be read-only
-  and can be moved/renamed without losing settings. See `app/paths.py`.
-- **Move-safe.** All paths are resolved at runtime from file locations and
-  `%APPDATA%` — never baked in — so moving the whole folder still works.
-
-### Which runtime: embeddable Python (not a venv)
-
-I used **python.org's embeddable Python 3.11 zip**, not an auto-created venv.
-Why: the embeddable build has **zero dependence on any system Python** (a venv
-needs a base interpreter to create it), it's a single self-contained folder, and
-it's the lightest way to get "nothing pre-installed." The one quirk it requires —
-enabling `site` / `Lib\site-packages` via the `._pth` file so pip-installed
-packages import — is handled deterministically in `ensure_runtime.bat`.
-
-This interpreter is **committed** under `runtime\`. It was created by
-`scripts\prepare_bundle.sh` (which just downloads + unzips the Windows build and
-`get-pip.py` on your Mac; nothing is executed on macOS) — re-run that only to
-rebuild or bump it.
-
-> Internet is needed on the **first** run only, to fetch the dependency wheels
-> from PyPI. Python itself is bundled. See [Offline / air-gapped
-> install](#4-offline--air-gapped-install) to remove the first-run download too.
-
-### The path/runtime/state helpers (load-bearing)
-
-| File | Role |
-|------|------|
-| `app/paths.py` | The ONE path helper. `resource_base()` (bundled resources, MEIPASS-aware), `state_dir()`/`user_state_dir()` (writable `%APPDATA%`), `is_packaged()`/`is_frozen()`. |
-| `app/config.py` | Derives `PROJECT_ROOT`, `STATE_DIR`, `ENV_PATH`, `LOG_DIR` from `app.paths`. |
-| `desktop_app.py` | The launcher: free port, in-process headless Streamlit, health-gated browser open, foreground serve. Sets `UPS_PACKAGED=1`. |
-| `scripts\prepare_bundle.sh` | Dev/**macOS/Linux**: (re)create `runtime\` (embeddable Python + `get-pip.py`). Rarely needed — `runtime\` is committed. |
-| `scripts\prepare_bundle.bat` | Dev/**Windows**: same, to rebuild a deleted runtime (downloads via PowerShell). |
-| `scripts\ensure_runtime.bat` | First-run: enable site-packages, install pip, pip-install the libraries. |
-| `scripts\run.bat` | Set `UPS_PACKAGED=1`, ensure runtime, then run in the foreground (normal or `debug`). |
-| `Start Upwork Proposal Strategist.bat` | Primary launcher (opens the browser; the console is the run indicator). |
-| `Start Upwork Proposal Strategist (Debug).bat` | Same app, with full logs for troubleshooting. |
-
-`UPS_PACKAGED=1` is how a non-frozen embeddable run still gets per-user state:
-`run.bat` and `desktop_app.py` set it; `app.paths.is_packaged()` honours it
-(alongside `sys.frozen`). Dev `streamlit run` leaves it unset → state stays in
-the repo root, so tests and local dev are unaffected.
-
----
-
-## 2. Run from source (developers)
-
-No PYTHONPATH needed. Pick either launch style.
-
-```bash
-# Install the libraries.
-pip install -r requirements.txt
-pip install -e .            # optional: `import app...` from anywhere + the
-                            # `upwork-strategist` console command
-
-# A) Exactly what the packaged app runs (opens your default browser):
-python desktop_app.py
-#    ...sets UPS_PACKAGED, so state goes to %APPDATA% (or
-#    ~/.upwork_proposal_strategist on macOS/Linux). Force dev state with:
-#    UPS_PACKAGED=0 python desktop_app.py   (mac/linux)   set UPS_PACKAGED=0   (win)
-
-# B) Plain Streamlit (state stays in the repo root):
-python -m streamlit run app/main.py
-```
-
-There is no longer a separate "native window" vs "browser" mode — both open in
-the browser. `pywebview` and `pythonnet` were removed.
-
-### Tests
-
-```bash
-pytest -q
-```
-
-The suite runs in dev mode (state in the repo root) and needs only
-`requirements.txt` — no desktop/GUI packages.
-
----
-
-## 3. Distributing the folder
-
-**One command builds a clean, ready-to-send zip:**
-
-```bash
-bash scripts/package.sh
-```
-
-It stages the bundled Python, copies the project while **excluding your secrets
-and dev junk** (`.env` / API key, `.git`, `.vscode`, `.claude`, caches, `logs`,
-`tests`, your personal `sample_dossier` files), writes
-`dist/UpworkProposalStrategist.zip`, and **aborts if a `.env` ever lands inside**.
-Re-run it after any change.
-
-**Send `dist/UpworkProposalStrategist.zip`.** The user unzips and double-clicks
-`Start Upwork Proposal Strategist`. Their first run installs the libraries from
-PyPI (internet needed once), then the app opens in their browser.
-
-> **The GitHub repo runs directly.** `runtime\` (the bundled Python) is
-> **committed**, so a `git clone` / "Download ZIP" already has `python.exe` —
-> double-click `Start Upwork Proposal Strategist` and it works (the first run
-> installs the libraries from PyPI; internet needed once). Only the first-run
-> *output* (`runtime\Lib`, `runtime\Scripts`, the `.deps_installed` marker) is
-> git-ignored.
-
-> Helper: `scripts/prepare_bundle.sh` (macOS/Linux) and `scripts/prepare_bundle.bat`
-> (Windows) (re)create `runtime\` from the pinned embeddable Python + `get-pip.py`.
-> You normally don't need them — the runtime is committed. Use them only to rebuild
-> a deleted/corrupted runtime or to bump the Python version. `package.sh` also calls
-> the `.sh` one (it's a no-op when the runtime is already present).
-
-> **Client vs repo:** both run, but the packaged `UpworkProposalStrategist.zip`
-> (from `package.sh`) is the cleaner hand-off for a non-technical client — it
-> strips `tests/`, `.git`, and dev files and gives a tidy folder name. The raw
-> GitHub download works too; it just also carries the dev files.
-
-To give it a real icon, create a Windows shortcut to
-`Start Upwork Proposal Strategist.bat`, set its icon to `build_assets\app.ico`,
-and place that shortcut on the Desktop.
-
-If antivirus/policy blocks the launcher, the user can double-click
-`scripts\run.bat` directly (same behaviour).
-
-> **Why this is friendlier to antivirus than the old build:** the previous
-> version used a hidden-launch `.vbs` *and* downloaded a Python interpreter at
-> runtime via PowerShell — both classic malware-heuristic / ASR triggers. This
-> version ships a plain `.bat`, bundles Python (no interpreter download), and
-> only lets `pip` fetch library wheels from PyPI (ordinary, not flagged the same
-> way). Note: unsigned code can still trip SmartScreen ("More info → Run
-> anyway"); the only real cure for that is code-signing, which is out of scope
-> here.
-
----
-
-## 4. Offline / air-gapped install
-
-The default already **bundles Python**, so the only thing a client downloads is
-the library wheels on first run. To make the folder **fully offline** (no
-internet even on the first run):
-
-1. **Bundle wheels:** on a machine with internet,
-   `pip download -r requirements.txt -d wheelhouse\` (from a Mac, add
-   `--platform win_amd64 --python-version 311 --only-binary=:all:` to fetch the
-   Windows wheels), ship the `wheelhouse\` folder, and change the install line in
-   `scripts\ensure_runtime.bat` to:
-   `"%PYEXE%" -m pip install --no-index --find-links "%ROOT%\wheelhouse" -r "%REQ%"`
-2. Python and `get-pip.py` are already committed under `runtime\`, so nothing
-   else is needed.
-
----
-
-## 5. Design notes
-
-- **Browser, not a native window.** The app opens in the default browser instead
-  of a pywebview/WebView2 window; `pywebview` + `pythonnet` were removed (fewer
-  moving parts, and `pythonnet`'s .NET interop was itself an extra antivirus
-  trigger). `127.0.0.1` is a browser "secure context", so clipboard paste on the
-  Job Screenshot screen still works; the file-upload control is the always-on
-  fallback. The console window is both the "running" indicator and the
-  clean-shutdown mechanism — close it and the single server process stops.
-  Streamlit binds to `127.0.0.1` **only** (verified with `lsof`: `TCP
-  127.0.0.1:<port> (LISTEN)`), so no network-facing port is ever exposed. A
-  first-run Windows Defender Firewall prompt for `python.exe` is therefore
-  harmless — a loopback listener works whether the user clicks **Allow access**
-  or **Cancel**. There is no clean non-admin way to suppress the prompt, so the
-  user docs just reassure (click Allow). Don't change the bind to `0.0.0.0`.
-- **PYTHONPATH dependence** was only in the *launch invocation* — the package is
-  well-formed (`__init__.py` throughout, absolute `app.x` imports). Fixed by
-  `pyproject.toml` (installable package) + the launcher's `sys.path` injection.
-- **conda** appeared only in docs; no code dependence.
-- **Writable state** previously redirected to `%APPDATA%` only when
-  `sys.frozen`; the embeddable run isn't frozen, so it would have written into
-  the folder. Fixed with the `UPS_PACKAGED` packaged-mode flag.
-- **Runtime decision:** embeddable Python (reasoning in §1).
-
----
-
-## 6. Verification checklist
-
-Items marked ✅ were verified on this (macOS) dev box; items marked 🪟 are
-Windows-only and must be checked on a clean Windows machine (the `.bat`
-bootstrap and the bundled `python.exe` can't run on macOS).
-
-| # | Check | Status |
-|---|-------|--------|
-| 1 | Fresh Windows, no Python: double-click → one-time library install w/ feedback → browser opens | 🪟 |
-| 2 | Second double-click: no reinstall, opens in seconds (marker fast-path) | 🪟 |
-| 3 | Runs with NO manual PYTHONPATH (imports as a package) | ✅ `pip install -e .` + import from `/tmp` |
-| 4 | Spaces in path, and moving the whole folder, still work | ✅ paths resolved from file locations; 🪟 end-to-end |
-| 5 | Setup saves API config to `%APPDATA%\...` and persists across restarts/moves | ✅ bootstrap + packaged-gate tests |
-| 6 | Bundled data files load in the relocated/bundled runtime | ✅ no path-based data reads; resources via `resource_base()` |
-| 7 | Clipboard paste + dossier picker work in the browser | 🪟 (paste = 127.0.0.1 secure context; upload fallback ✅) |
-| 8 | Console stays open as the run indicator; debug launcher shows logs | 🪟 (`UPS_DEBUG=1` raises the log level) |
-| 9 | Closing the console leaves no orphan `python.exe` | ✅ single process; 🪟 end-to-end |
-| 10 | Interrupted first-run setup self-heals next double-click | 🪟 (marker written last) |
-| 11 | `prepare_bundle.sh` stages `runtime\` (python.exe + get-pip.py) | ✅ runs on macOS |
-| 12 | `SHOW_DEBUG_PANEL` still toggles | ✅ unchanged; tests pass |
-
-To verify the Windows-only items, run `build`-free on a clean VM: stage the
-bundle, copy the folder, double-click the launcher, and walk the checklist. Use
-`Start Upwork Proposal Strategist (Debug).bat` to see logs if anything fails.

README.md

@@ -45,11 +45,12 @@ The app walks you through five steps in the left sidebar:
 > ⚠️ The **Job Screenshot** step needs a vision-capable provider — use
 > **OpenAI**, **Anthropic**, or **Gemini**. **Groq cannot read images.**
 
-## Running locally
+## Step-by-step user guide
+
+A complete, click-by-click walkthrough is included in this repo:
+**[Upwork-Proposal-Strategist-Guide.pdf](Upwork-Proposal-Strategist-Guide.pdf)**.
 
-This same code also runs as a local desktop app where you point it at a folder
-on your machine instead of uploading. See **README_DESKTOP.md** and
-**DEVELOPER.md** for that path.
+## Running locally
 
 ```bash
 pip install -r requirements.txt

desktop_app.py

@@ -1,271 +0,0 @@
-"""Browser launcher for the Upwork Proposal Strategist.
-
-What this does
---------------
-The app is a local Streamlit server. This launcher starts that server and opens
-it in the user's **default web browser** — there is no native window and no
-extra GUI runtime (no pywebview / WebView2 / .NET). It runs in the **foreground**,
-so the console window it launches from is the "app is running" indicator:
-closing that window stops the server cleanly.
-
-Flow
-----
-1. Declare packaged-desktop mode (``UPS_PACKAGED=1``) so writable state — the
-   API-key ``.env`` and rotating logs — goes to ``%APPDATA%`` instead of the
-   (possibly read-only / relocatable) install folder. See :mod:`app.paths`.
-2. Create the per-user ``.env`` from the bundled template on first run.
-3. Pick a FREE local port (never hard-code 8501, so two copies don't collide).
-4. On a background thread, wait for the server's health endpoint and then open
-   the browser at the local URL — opening only once it actually answers avoids a
-   "can't connect" tab on the slow first launch.
-5. Run Streamlit **headless**, bound to 127.0.0.1, in the foreground. It serves
-   until the console window is closed (or Ctrl+C), which cleanly stops it.
-
-Design notes
-------------
-* ONE process. The launcher *is* the Streamlit server: its stable CLI is driven
-  in-process by :func:`run_streamlit_cli`. There is no child process, GUI library,
-  or re-exec, so closing the console is the clean, orphan-free shutdown — nothing
-  to taskkill.
-* 127.0.0.1 is a browser "secure context", so clipboard paste on the Job
-  Screenshot screen keeps working; the file-upload control is always available
-  too.
-* Writable state is handled by :mod:`app.config`, which redirects to a per-user
-  location when packaged — see DEVELOPER.md.
-"""
-
-from __future__ import annotations
-
-import os
-import shutil
-import socket
-import sys
-import threading
-import time
-import urllib.request
-import webbrowser
-from pathlib import Path
-
-# Put the project root (this file's own directory, which holds the `app`
-# package) on sys.path BEFORE importing app. A normal Python auto-prepends the
-# script's directory, but the Windows embeddable Python uses a ._pth file that
-# does NOT — so without this the very first `import app` dies with
-# "ModuleNotFoundError: No module named 'app'". This is a no-op under a normal
-# dev Python (the directory is already there). Must run before any `from app…`.
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-
-# The one shared path helper (stdlib-only, no import cycle).
-from app.paths import PACKAGED_ENV_FLAG, resource_base
-
-
-# Mirrors app.config.APP_TITLE. Kept as a literal so the launcher can print the
-# banner without importing the (heavier) app package first.
-APP_TITLE = "Upwork Proposal Strategist"
-
-# How long to wait for the Streamlit server to answer before opening the browser
-# anyway. The first run imports a lot (and antivirus can slow it), so this is
-# deliberately generous.
-BOOT_TIMEOUT = 90.0
-
-
-def _main_script() -> Path:
-    """Absolute path to the Streamlit entry script Streamlit will execute."""
-    return resource_base() / "app" / "main.py"
-
-
-# ---------------------------------------------------------------------------
-# Streamlit server (driven in-process via its own stable CLI)
-# ---------------------------------------------------------------------------
-
-
-def run_streamlit_cli(port: int) -> None:
-    """Run the Streamlit server (headless) on ``port``. Blocks until stopped.
-
-    Points Streamlit at the bundled ``app/main.py`` and pins every server option
-    on the command line so behavior never depends on a config file being found.
-    Working directory is the resource base so ``import app...`` resolves and the
-    bundled ``.streamlit/config.toml`` (theme, toolbar) is still picked up.
-    """
-    base = resource_base()
-    # CWD so Streamlit finds .streamlit/config.toml; sys.path so `import app`
-    # works when Streamlit execs app/main.py.
-    os.chdir(str(base))
-    if str(base) not in sys.path:
-        sys.path.insert(0, str(base))
-
-    # Quiet console on a normal run; full logs when launched via the debug .bat.
-    log_level = "debug" if os.environ.get("UPS_DEBUG") == "1" else "error"
-    sys.argv = [
-        "streamlit",
-        "run",
-        str(_main_script()),
-        "--server.address=127.0.0.1",
-        f"--server.port={port}",
-        "--server.headless=true",            # we open the browser ourselves
-        "--browser.gatherUsageStats=false",  # local-first: no telemetry call
-        "--server.fileWatcherType=none",     # packaged app: nothing to hot-reload
-        "--server.runOnSave=false",
-        # Local single-user desktop context: these clear the 403 upload error
-        # local proxies otherwise trigger on st.file_uploader. Mirrors the
-        # bundled .streamlit/config.toml.
-        "--server.enableCORS=false",
-        "--server.enableXsrfProtection=false",
-        "--server.maxUploadSize=20",
-        f"--logger.level={log_level}",
-    ]
-    # Imported here (not at module top) so the cost is only paid in the process
-    # that actually serves, and import errors surface in the console.
-    from streamlit.web import cli as stcli
-
-    sys.exit(stcli.main())
-
-
-# ---------------------------------------------------------------------------
-# Port / health / browser
-# ---------------------------------------------------------------------------
-
-
-def pick_free_port() -> int:
-    """Return an OS-assigned free TCP port on the loopback interface.
-
-    Binding to port 0 lets the kernel hand us a port nothing else holds, so a
-    second instance never collides with the first. The socket is closed
-    immediately; Streamlit re-binds the same port a moment later.
-    """
-    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
-        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-        sock.bind(("127.0.0.1", 0))
-        return int(sock.getsockname()[1])
-
-
-def _health_ok(port: int) -> bool:
-    """True if the Streamlit server answers its health endpoint with HTTP 200."""
-    # /_stcore/health is current; /healthz covers older Streamlit just in case.
-    for path in ("/_stcore/health", "/healthz"):
-        try:
-            with urllib.request.urlopen(
-                f"http://127.0.0.1:{port}{path}", timeout=2
-            ) as resp:
-                if resp.status == 200:
-                    return True
-        except Exception:  # noqa: BLE001 - not up yet / endpoint absent → try next
-            continue
-    return False
-
-
-def _page_ok(port: int) -> bool:
-    """True if the root page itself serves real HTML (not just the health ping).
-
-    The health endpoint flips to 200 the instant the server process is up —
-    a split second BEFORE Streamlit can actually render the page. Opening the
-    browser in that gap leaves a blank tab that needs a manual refresh. We
-    additionally confirm the root URL returns HTML so the page is genuinely
-    ready before we open it.
-    """
-    try:
-        with urllib.request.urlopen(
-            f"http://127.0.0.1:{port}/", timeout=3
-        ) as resp:
-            if resp.status != 200:
-                return False
-            body = resp.read(4096).decode("utf-8", "ignore").lower()
-            # Streamlit's shell always contains these markers once it serves.
-            return ("streamlit" in body) or ("<div id=\"root\"" in body) or ("<title" in body)
-    except Exception:  # noqa: BLE001 - not serving the page yet
-        return False
-
-
-def _open_browser_when_ready(
-    port: int, url: str, timeout: float = BOOT_TIMEOUT
-) -> None:
-    """Wait for the server to be healthy, then open the default browser once.
-
-    Runs on a daemon thread so the main thread is free to serve. If the server
-    never comes up within ``timeout`` we still open the browser once, so the
-    user sees the address (and any browser-side error) rather than nothing.
-    """
-    deadline = time.monotonic() + timeout
-    ready = False
-    while time.monotonic() < deadline:
-        # Require BOTH the health ping AND the root page to serve real HTML,
-        # so the browser never opens onto a blank, not-yet-rendered shell.
-        if _health_ok(port) and _page_ok(port):
-            ready = True
-            break
-        time.sleep(0.4)
-    # A short settle delay after the page first serves — Streamlit needs a
-    # moment more before the websocket-driven first render is reliably ready.
-    if ready:
-        time.sleep(1.2)
-    try:
-        webbrowser.open(url)
-    except Exception:  # noqa: BLE001 - never crash the server if no browser opens
-        pass
-
-
-# ---------------------------------------------------------------------------
-# First-run setup
-# ---------------------------------------------------------------------------
-
-
-def _bootstrap_env() -> None:
-    """Create the per-user ``.env`` from the bundled template on first run.
-
-    The write target comes from :data:`app.config.ENV_PATH`, which already
-    redirects to ``%APPDATA%\\UpworkProposalStrategist`` when packaged, so the
-    Setup screen and this bootstrap always agree on one location.
-    """
-    try:
-        from app.config import ENV_PATH  # packaged-aware target
-    except Exception:  # noqa: BLE001 - never block launch on config import
-        return
-    if ENV_PATH.exists():
-        return
-    try:
-        ENV_PATH.parent.mkdir(parents=True, exist_ok=True)
-        template = resource_base() / ".env.example"
-        if template.is_file():
-            shutil.copyfile(template, ENV_PATH)
-        else:
-            ENV_PATH.write_text("LLM_PROVIDER=openai\n", encoding="utf-8")
-    except OSError:  # pragma: no cover - best effort; Setup can still write it
-        pass
-
-
-# ---------------------------------------------------------------------------
-# Entry point
-# ---------------------------------------------------------------------------
-
-
-def main() -> None:
-    # Declare packaged-desktop mode (unless explicitly overridden) so app.config
-    # redirects writable state — the API-key .env and logs — to %APPDATA%
-    # instead of the read-only / relocatable install folder. A developer can
-    # force dev behaviour with UPS_PACKAGED=0.
-    os.environ.setdefault(PACKAGED_ENV_FLAG, "1")
-
-    _bootstrap_env()
-    port = pick_free_port()
-    url = f"http://127.0.0.1:{port}"
-
-    # Print the address up front (with logger.level=error the console stays
-    # readable) so the user can open it manually if their browser doesn't.
-    print(
-        f"\n{APP_TITLE} is starting…\n"
-        f"If your browser does not open automatically, go to:  {url}\n",
-        flush=True,
-    )
-
-    # Open the browser from a daemon thread once the server answers; meanwhile
-    # the main thread serves below.
-    threading.Thread(
-        target=_open_browser_when_ready, args=(port, url), daemon=True
-    ).start()
-
-    # Serve in the foreground. Closing the console window (or Ctrl+C) stops the
-    # server — single process, so there is no child to orphan.
-    run_streamlit_cli(port)
-
-
-if __name__ == "__main__":
-    main()

docs/FIRST_TIME_SETUP_GUIDE.md

@@ -1,377 +0,0 @@
-# First Time Setup Guide
-
-This guide is for people who have **never** done anything like this before. That's okay. Just follow the steps in order. Do one, then go to the next.
-
-The main way to use this tool is the **Windows app**: you **double-click one file** and it opens in your **web browser**. The very first time, it sets itself up automatically (one time, a few minutes, needs internet). **No terminal. No installing anything yourself. No setup commands.**
-
-> 💡 **Tip:** Do not skip steps. Do them top to bottom: 1, 2, 3…
-
-> ℹ️ **On a Mac, or a developer?** This guide is for the Windows app. Running from the source code is covered in [DEVELOPER.md](../DEVELOPER.md); the in-app steps (3–8) are the same.
-
----
-
-## How to read this guide
-
-- A **button** or thing you click is shown in **bold**.
-- After each step, the guide tells you **what you should see**.
-- 📷 means a picture can be added there later.
-
----
-
-## Table of Contents
-
-- [What This Tool Does](#what-this-tool-does)
-- [Things You Need Before Starting](#things-you-need-before-starting)
-- [Step 1: Open the App (first time)](#step-1-open-the-app-first-time)
-- [Step 2: Opening It Again](#step-2-opening-it-again)
-- [Step 3: Connect Your AI Service](#step-3-connect-your-ai-service)
-- [Step 4: Run the API Check](#step-4-run-the-api-check)
-- [Step 5: Add Your Dossier](#step-5-add-your-dossier)
-- [Step 6: Add the Job Screenshot](#step-6-add-the-job-screenshot)
-- [Step 7: Read the Analysis](#step-7-read-the-analysis)
-- [Step 8: Generate Your Proposal](#step-8-generate-your-proposal)
-- [Common Problems and Fixes](#common-problems-and-fixes)
-- [Safe Practices](#safe-practices)
-- [Mac, or Running From Source](#mac-or-running-from-source)
-
----
-
-## What This Tool Does
-
-This tool is the **Upwork Proposal Strategist**.
-
-On Upwork, people send a message called a **proposal** to win freelance jobs. This tool helps you write a good proposal fast.
-
-Here's what it does:
-
-1. You give it a folder with your work files (resume, past projects, and so on).
-2. You give it a **picture** of an Upwork job.
-3. It compares the job to your files.
-4. It gives you a clear **verdict**: 🟢 Apply Confidently · 🟡 Proceed With Caution · 🔴 Do Not Proceed.
-5. It writes a first draft of your proposal, using only true facts from your files.
-
-> 💡 **Tip:** Everything runs on your own computer. Your files stay with you.
-
----
-
-## Things You Need Before Starting
-
-A short checklist. The guide shows you how to get each one.
-
-- [ ] **A Windows 10 or 11 computer.**
-- [ ] **The app folder** — usually a ZIP file someone sent you, named something like `UpworkProposalStrategist.zip`.
-- [ ] **Internet** (Wi-Fi or cable) — needed the first time so the app can set itself up.
-- [ ] **An API key** — a secret password for an AI service. You get one in **Step 3**.
-
-> ℹ️ **Note:** You do **not** need to install Python or open a terminal. The app sets up everything it needs by itself, the first time you open it.
-
----
-
-## Step 1: Open the App (first time)
-
-**Do this:**
-
-1. If you were sent a **ZIP**, right-click it → **Extract All…** → **Extract**. You now have a folder (for example `UpworkProposalStrategist`).
-2. Open that folder and **double-click** the file named **`Start Upwork Proposal Strategist`**.
-3. Windows may show a blue box (**"Windows protected your PC"**). This is normal for a new app that isn't signed yet.
-   - Click **More info**, then **Run anyway**.
-4. A small **black setup window** appears and says it's doing a **one-time setup**. It works for a few minutes. **Leave it alone until it finishes** — it's downloading and installing everything the app needs, just this once.
-
-**You should see:** After setup, the app opens in your **web browser** on the **Setup** page. The small black window stays open behind it — that's normal; leave it open while you use the app.
-
-> ✅ **Success:** The app is open in your browser. Continue to **Step 3**.
-
-> 💡 **Tip:** The first time is the slow time (a few minutes, needs internet). Every launch after that takes only a few seconds.
-
-> 🔒 **If Windows asks about the firewall:** A box may appear saying *"Windows Defender Firewall has blocked some features of python."* Click **Allow access** (you can leave **Public networks** unchecked). It's safe — the app only talks to **your own computer**. Even if you click **Cancel**, the app still works.
-
-> ℹ️ **Note:** Five pages run down the **left side**: **Setup**, **Dossier**, **Job Screenshot**, **Analysis**, **Proposal**. A lock (🔒) is normal — each unlocks when you finish the one before it.
-
-> ⚠️ **If the browser doesn't open on its own:** the black window shows a web address like `http://127.0.0.1:…` — type that into your browser. See [Common Problems → App won't open](#common-problems-and-fixes).
-
-> 📷 *Screenshot placeholder: the "one-time setup" window, then the app on Setup.*
-
----
-
-## Step 2: Opening It Again
-
-Next time you want to use the tool:
-
-- Open the app folder and **double-click `Start Upwork Proposal Strategist`** again.
-- No setup this time — it opens in your browser in a few seconds.
-
-> 💡 **Tip:** To make it easier later, right-click **`Start Upwork Proposal Strategist`** → **Send to → Desktop (create shortcut)**. Then it's one click from your Desktop.
-
-> ✅ **Success:** The app opens in your browser. Your AI key from last time is remembered, so you can usually go straight to **Step 5**.
-
----
-
-## Step 3: Connect Your AI Service
-
-Now you tell the app which AI service to use and give it your secret key. This is on the **Setup** page. You only do this **once** — the app remembers it next time.
-
-### Pick an AI service
-
-You only need **one**:
-
-- **OpenAI** — popular and easy. A good first choice. Can read pictures.
-- **Anthropic** — makes the "Claude" AI. Can read pictures.
-- **Gemini** — Google's AI. Can read pictures.
-- **Groq** — fast and cheap, but **cannot read pictures** (so the screenshot step won't work).
-
-> ✅ **Recommended:** Pick **OpenAI**, **Anthropic**, or **Gemini** so screenshots work.
-
-### Get a key
-
-1. Open the website for your service:
-   - **OpenAI:** `https://platform.openai.com/api-keys`
-   - **Anthropic:** `https://console.anthropic.com/`
-   - **Gemini:** `https://aistudio.google.com/app/apikey`
-   - **Groq:** `https://console.groq.com/keys`
-2. Sign up or log in.
-3. Click a button like **Create new secret key**.
-4. **Copy** the key (a long line of letters and numbers).
-
-> ⚠️ **Warning:** The key is shown only once — copy it right away. These services can cost money based on use; check their pricing.
-
-### Fill in the Setup page
-
-The service names are lowercase: `openai`, `anthropic`, `groq`, `gemini`.
-
-1. In **LLM Provider**, pick your service.
-2. In **LLM Model**, leave the one already filled in.
-3. Paste your key into the **API Key** box. ("Paste" = press **Ctrl + V**.)
-4. In **Vision Provider**, pick **`same_as_llm`** (this reuses your choice, so you only need one key).
-5. Click **Save Configuration**.
-
-**You should see:** A message like `Configuration saved. Run API Check to continue.`
-
-> ⚠️ **Warning:** Do not pick **Groq** for **Vision Provider** — it cannot read pictures.
-
-> 📷 *Screenshot placeholder: the Setup page with the fields filled in.*
-
----
-
-## Step 4: Run the API Check
-
-This tests your key.
-
-**Do this:** Click the **Run API Check** button.
-
-**You should see (good):** A green message: `AI service is ready.` A **Continue to Dossier** button appears.
-
-> ✅ **Success:** You see `AI service is ready.` Click **Continue to Dossier**.
-
-**You should see (problem):** A red message, like `The API key or model could not be validated.`
-
-If you see a red message, check these:
-
-- The key was copied with no extra spaces.
-- The **LLM Provider** matches your key (an OpenAI key needs OpenAI).
-- Your internet works, and your account has credit.
-
-Then click **Save Configuration** again, and **Run API Check** again.
-
----
-
-## Step 5: Add Your Dossier
-
-A **dossier** is just your folder of work files. The app reads it as proof of what you can do.
-
-### Put files in one folder
-
-Make one folder and put your work files in it. The app can read these types:
-
-- PDF (`.pdf`), Word (`.docx`), Text (`.txt`), Markdown (`.md`)
-- Data (`.json`, `.csv`)
-- Images (`.png`, `.jpg`, `.jpeg`)
-
-Good things to add: resume / CV, portfolio, testimonials or reviews, case studies, certifications, work samples.
-
-> 💡 **Tip:** To try it the first time, use the folder named `sample_dossier` that came with the project.
-
-> ⚠️ **Warning:** Do not put private files (passwords, bank files) in this folder.
-
-### Get the folder's path
-
-A **path** is the full address of a folder. In **File Explorer**, hold **Shift**, right-click the folder, and choose **Copy as path**.
-
-> 💡 **Tip:** Folders with spaces in the name (like `My Work Files`) are fine.
-
-### Do it in the app
-
-On the **Dossier** page:
-
-1. Paste the path into the **Dossier folder path** box (**Ctrl + V**).
-2. Click **Continue to Job Screenshot**.
-
-The app reads your files behind the scenes and moves you to the next page.
-
-> ✅ **Success:** You land on the **Job Screenshot** page.
-
-> ⚠️ **Warning:** If you see "Couldn't read that folder", the path was wrong or the folder had no readable files. Re-copy the path and try again.
-
-> 📷 *Screenshot placeholder: the Dossier page.*
-
----
-
-## Step 6: Add the Job Screenshot
-
-A **screenshot** is a picture of your screen. Take a picture of the Upwork job you want.
-
-### Take the picture
-
-- Press **Windows + Shift + S**. Drag a box around the whole job post.
-- The picture is now copied, ready to paste.
-
-> 💡 **Tip:** Capture the whole job post — title, description, skills, and budget.
-
-### Add it in the app
-
-On the **Job Screenshot** page, you have **two easy ways**:
-
-- **Paste it:** click **📋 Paste screenshot from clipboard** (works right after the step above). *— easiest*
-- **Or upload a file:** click **Browse files** and pick a saved picture. Types: **PNG, JPG, JPEG, WEBP**, each **20 MB or smaller**.
-
-Then:
-
-1. Check it says a screenshot is ready.
-2. Click **Analyze Opportunity**.
-
-The app reads the job from your picture and goes straight to the **Analysis** page.
-
-> ✅ **Success:** The app reads the picture and shows the Analysis.
-
-> ⚠️ **Warning:** If you picked **Groq**, this step won't work. Go back to **Setup** and pick OpenAI, Anthropic, or Gemini.
-
-> 💡 **Tip:** If the **📋 Paste** button doesn't pick up your screenshot, save it as a PNG/JPG and use **Browse files** instead — that always works.
-
-> 📷 *Screenshot placeholder: the Job Screenshot page.*
-
----
-
-## Step 7: Read the Analysis
-
-The **Analysis** page compares the job to your files and shows a clear verdict.
-
-**You should see:**
-
-1. A **Verdict** — one of:
-   - 🟢 **Apply Confidently** — a good match; go for it.
-   - 🟡 **Proceed With Caution** — possible, but check the concerns first.
-   - 🔴 **Do Not Proceed** — likely not worth your connects.
-2. A few **short reasons** for the verdict.
-3. **Key strengths** — why you fit.
-4. **Concerns** — what may count against you.
-5. Sometimes a **Heads up** card naming job details that weren't visible in the picture.
-
-**Do this:** Read the results. When ready, click **Continue to Proposal**.
-
-> 💡 **Tip:** Click **Re-run Analysis** at the top if you want a fresh result.
-
-> 📷 *Screenshot placeholder: the Analysis page with the verdict.*
-
----
-
-## Step 8: Generate Your Proposal
-
-The **Proposal** page writes your proposal draft, using only facts from your files.
-
-**Do this:**
-
-1. Click **Generate Proposal**.
-2. Wait a moment for the draft to appear in the box.
-3. Click **Copy Proposal** (to copy) or **Download as .txt** (to save). Paste it into Upwork.
-
-> ℹ️ **Note:** If the verdict was 🔴 **Do Not Proceed**, the button is off. To force a draft anyway, first tick **Yes, generate the proposal anyway**.
-
-> 💡 **Tip:** This is a first draft. Read it, add your own voice, and fix anything before you send it.
-
-> ✅ **Success:** Your proposal draft is ready.
-
-> 📷 *Screenshot placeholder: the Proposal page with a finished draft.*
-
----
-
-## When You're Done
-
-- Close the small **black status window** that opened with the app (the one that says it's running). That quits the app — there's nothing else to stop. You can also close the browser tab.
-- Your AI settings are saved, so next time you only do Steps 5–8.
-
-> 💡 **Tip:** Next time, use the shorter [QUICK_START_GUIDE.md](QUICK_START_GUIDE.md) in this same `docs` folder.
-
----
-
-## Common Problems and Fixes
-
-### Browser didn't open on its own
-
-- The small **black window** shows a web address like `http://127.0.0.1:8xxx`. Open your browser (Chrome, Edge, Firefox…) and type that address into the bar.
-- The **first** launch is just slow (it's installing — give it a few minutes, and make sure you have internet that first time). Later launches take only seconds.
-- If you closed the black window, the app stops. Double-click **`Start Upwork Proposal Strategist`** again to reopen it.
-
-### "Windows protected your PC"
-
-- Expected for a new app that isn't signed yet. Click **More info → Run anyway**. It is safe.
-
-### A "Windows Firewall" box about "python"
-
-- Normal on the first run. To show its pages in your browser, the app runs a tiny server on **your own computer** — Windows just wants you to okay it. Click **Allow access** (you can leave **Public networks** unchecked).
-- It's safe: nothing is opened to the internet. The server only listens on your own machine (`127.0.0.1`), so even if you click **Cancel**, the app keeps working.
-
-### Double-clicking does nothing / the launcher is blocked
-
-- If antivirus blocked the launcher, open the app folder, go into the **`scripts`** folder, and double-click **`run.bat`** instead — it does exactly the same thing.
-- If files seem to be missing, your antivirus may have removed them. Re-download the folder, **allow** it when prompted, and fully **Extract All** before opening.
-
-### API not working
-
-- Re-copy your key (watch for extra spaces).
-- Make sure the **LLM Provider** matches your key.
-- Check your internet and your account credit.
-- Click **Save Configuration**, then **Run API Check** again.
-
-### Screenshot not working
-
-- Use a **PNG, JPG, JPEG, or WEBP** picture, **20 MB or smaller**.
-- **Groq cannot read pictures.** On **Setup**, set **Vision Provider** to OpenAI, Anthropic, or Gemini.
-- If the **📋 Paste** button doesn't catch your screenshot, save it as a file and use **Browse files**.
-
-### I need to change or remove my saved key
-
-- Go to **Setup**. Type a new key and **Save Configuration**, or click **Clear Credentials** to wipe the saved key.
-- Your key is stored privately in `%APPDATA%\UpworkProposalStrategist\.env`.
-
-### Start over completely
-
-- Close the app. Then open **File Explorer**, click the address bar at the top, type `%APPDATA%\UpworkProposalStrategist` and press **Enter** — it opens the app's private folder. Delete that folder (this removes your saved key and logs). Open the app again to set up fresh.
-
----
-
-## Safe Practices
-
-> ⚠️ **Warning:** Follow these to stay safe.
-
-### Never share your API key
-
-- It's a secret password. Anyone with it can spend your money.
-- Never put it in chats, emails, or screenshots.
-- If it leaks, delete it on the provider's website and make a new one.
-
-### Never share the `.env` file
-
-- The app saves your key in a hidden file named `.env` (in `%APPDATA%\UpworkProposalStrategist\` for the installed app).
-- Never send this file to anyone or put it online.
-
-### Keep backup copies
-
-- Keep a spare copy of your **dossier folder**.
-- Save any proposal drafts you like.
-
----
-
-## Mac, or Running From Source
-
-This guide is for the **Windows app**. If you're on a **Mac/Linux**, or you're a developer who wants to run the project's source code, see **[DEVELOPER.md](../DEVELOPER.md)**. It explains how to start the app (no conda and no PYTHONPATH needed). Once the app is open in your browser, the in-app steps **3–8 above are identical**.
-
-> ℹ️ **Note (for whoever hands this out):** To package it so end users just double-click, see [DEVELOPER.md](../DEVELOPER.md).

docs/QUICK_START_GUIDE.md

@@ -1,65 +0,0 @@
-# Quick Start Guide
-
-**Use this after your first time** (see `FIRST_TIME_SETUP_GUIDE.md`). It's the short version for using the tool again. If something doesn't work, open the full guide and check **Common Problems and Fixes**.
-
-> 💡 **Tip:** There's no terminal and no setup to repeat — your AI key is already saved.
-
----
-
-## Open the app
-
-- Open the app folder and **double-click `Start Upwork Proposal Strategist`** (or its Desktop shortcut, if you made one).
-- A small status window opens, then the app appears in your **web browser** after a few seconds. Leave that status window open while you use the app.
-
-> 🔒 **Tip:** If Windows ever shows a firewall box about **"python"**, click **Allow access** — it's safe (the app only uses your own computer). Clicking Cancel works too.
-
-> ℹ️ **Note:** The five pages are on the **left**: **Setup**, **Dossier**, **Job Screenshot**, **Analysis**, **Proposal**. They unlock in order (🔒 is normal).
-
----
-
-## The 4 steps
-
-### 1. Setup (only if needed)
-
-Your AI key is saved from last time, so you can usually skip straight to step 2.
-
-- If a page is locked, go to **Setup** and click **Run API Check**. Wait for `AI service is ready.`, then **Continue to Dossier**.
-- Changing services or key? Update the fields, click **Save Configuration**, then **Run API Check**.
-
-### 2. Dossier
-
-- On **Dossier**, paste your work-files folder path into **Dossier folder path**.
-- Click **Continue to Job Screenshot**.
-
-> 💡 **Tip:** Get the path in File Explorer: hold **Shift**, right-click the folder → **Copy as path**.
-
-### 3. Job Screenshot
-
-- Take a screenshot of the Upwork job: **Windows + Shift + S**, drag a box around the whole post.
-- On **Job Screenshot**, click **📋 Paste screenshot from clipboard** (or **Browse files** for a saved PNG/JPG).
-- Click **Analyze Opportunity**. The app jumps to the Analysis.
-
-> ⚠️ **Warning:** The **Groq** provider can't read screenshots. Use **OpenAI**, **Anthropic**, or **Gemini** as your **Vision Provider**.
-
-### 4. Analysis → Proposal
-
-- On **Analysis**, read the verdict — 🟢 **Apply Confidently** · 🟡 **Proceed With Caution** · 🔴 **Do Not Proceed** — plus your strengths and concerns. Click **Continue to Proposal**.
-- On **Proposal**, click **Generate Proposal**, then **Copy Proposal** or **Download as .txt**.
-
-> ℹ️ **Note:** If the verdict is 🔴 **Do Not Proceed**, tick **Yes, generate the proposal anyway** to enable the button.
-
-> ✅ **Success:** You have a finished proposal draft. Review it, add your own voice, and send it on Upwork.
-
----
-
-## When you're done
-
-- Close the small **status window** that opened with the app (the one that says it's running). That quits the app. You can also close the browser tab.
-
-> 💡 **Tip:** Never share your API key or your `.env` file. See **Safe Practices** in `FIRST_TIME_SETUP_GUIDE.md`.
-
----
-
-## Mac, or running from source?
-
-This is for the Windows app. To run from the source code (Mac/Linux or developers), see **[../DEVELOPER.md](../DEVELOPER.md)** — no conda or PYTHONPATH needed. The 4 steps above are the same once the app is open in your browser.

pyproject.toml

@@ -1,37 +0,0 @@
-# Packaging metadata for the Upwork Proposal Strategist.
-#
-# Purpose: make the project a PROPER importable package so the app runs with
-# NO manual PYTHONPATH. After `pip install -e .` the `app` package and the
-# `desktop_app` launcher import from anywhere.
-#
-# Dependencies are intentionally NOT duplicated here. The pinned, single source
-# of truth is requirements.txt, which is what the first-run bootstrap installs.
-# Declaring them again here would invite drift. The app runs in the browser, so
-# there is no native-window dependency stack to mirror.
-
-[build-system]
-requires = ["setuptools>=68"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "upwork-proposal-strategist"
-version = "1.0.0"
-description = "Local-first desktop app that scores Upwork jobs against your dossier and drafts grounded proposals."
-readme = "README.md"
-requires-python = ">=3.11"
-dependencies = []  # see requirements.txt (pinned, single source of truth)
-
-[project.scripts]
-# Lets a developer launch the app (browser) with a bare `upwork-strategist`.
-upwork-strategist = "desktop_app:main"
-
-[tool.setuptools]
-# desktop_app.py lives at the repo root as a single module (the launcher).
-py-modules = ["desktop_app"]
-
-[tool.setuptools.packages.find]
-# Ship the application package (and its subpackages); leave tests out.
-include = ["app*"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]

scripts/ensure_runtime_mac.sh

@@ -1,123 +0,0 @@
-#!/usr/bin/env bash
-# ===========================================================================
-#  ensure_runtime_mac.sh — first-run setup for macOS.
-#
-#  What it does:
-#    1. Verifies Python 3.9+ is available on the system.
-#    2. Creates a local virtual environment at runtime_mac/venv/ (once).
-#    3. Installs the app's libraries from requirements.txt (once).
-#    4. Writes a success marker (runtime_mac/.deps_installed) so subsequent
-#       launches skip all of this — instant no-op.
-#
-#  Idempotent: safe to run multiple times. A partial/failed run leaves no
-#  marker, so it resumes cleanly on the next launch.
-#
-#  Called by run_mac.sh. Never run this directly.
-# ===========================================================================
-
-set -euo pipefail
-
-# Resolve the project root (this script lives in <root>/scripts/).
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-ROOT="$( cd "$SCRIPT_DIR/.." && pwd )"
-
-VENV="$ROOT/runtime_mac/venv"
-MARKER="$ROOT/runtime_mac/.deps_installed"
-REQ="$ROOT/requirements.txt"
-PYEXE="$VENV/bin/python"
-
-# ── Fast path: already set up ─────────────────────────────────────────────
-if [ -f "$MARKER" ]; then
-    exit 0
-fi
-
-# ── Find Python 3.9+ ──────────────────────────────────────────────────────
-find_python() {
-    for cmd in python3.12 python3.11 python3.10 python3.9 python3; do
-        if command -v "$cmd" &>/dev/null; then
-            ver=$("$cmd" -c "import sys; print(sys.version_info >= (3,9))" 2>/dev/null)
-            if [ "$ver" = "True" ]; then
-                echo "$cmd"
-                return 0
-            fi
-        fi
-    done
-    return 1
-}
-
-if ! PYTHON=$(find_python); then
-    echo ""
-    echo "============================================================"
-    echo "  Python 3.9 or newer is required but was not found."
-    echo ""
-    echo "  To install Python on your Mac:"
-    echo "    1. Go to https://www.python.org/downloads/"
-    echo "    2. Download the latest macOS installer"
-    echo "    3. Run the installer, then launch this app again."
-    echo ""
-    echo "  (Alternatively, if you have Homebrew: brew install python3)"
-    echo "============================================================"
-    echo ""
-    exit 1
-fi
-
-echo ""
-echo "============================================================"
-echo "  Upwork Proposal Strategist - one-time setup"
-echo ""
-echo "  This runs ONCE and downloads the app's libraries"
-echo "  (about 150 MB). It usually takes 2-5 minutes the first"
-echo "  time, depending on your internet speed."
-echo ""
-echo "  >> Progress is shown below. This is NOT stuck - please"
-echo "     wait until you see 'Setup complete.'"
-echo "============================================================"
-echo ""
-
-_fail() {
-    echo ""
-    echo "============================================================"
-    echo "  SETUP DID NOT COMPLETE"
-    echo "  $1"
-    echo ""
-    echo "  Check your internet connection and try launching again -"
-    echo "  setup resumes safely from where it stopped."
-    echo "  (For full details, use 'Troubleshoot (Mac).command'.)"
-    echo "============================================================"
-    echo ""
-    exit 1
-}
-
-using_python_version="$("$PYTHON" -c 'import sys;print(".".join(map(str,sys.version_info[:3])))' 2>/dev/null)"
-echo "[setup] Using Python $using_python_version ($PYTHON)"
-
-# ── Create the virtual environment ────────────────────────────────────────
-mkdir -p "$ROOT/runtime_mac"
-echo "[setup] Creating an isolated Python environment..."
-# Explicit failure handling: with 'set -e', a bare failing command would exit
-# before our friendly message — 'if !' keeps the message visible.
-if ! "$PYTHON" -m venv "$VENV"; then
-    _fail "Could not create the Python environment (python3 -m venv failed)."
-fi
-if [ ! -x "$PYEXE" ]; then
-    _fail "The Python environment is missing its interpreter at $PYEXE."
-fi
-
-# ── Upgrade pip inside the venv ────────────────────────────────────────────
-echo "[setup] Preparing the installer (pip)..."
-if ! "$PYEXE" -m pip install --upgrade pip --disable-pip-version-check; then
-    _fail "Could not prepare pip (the installer)."
-fi
-
-# ── Install dependencies (progress shown — NOT silent) ─────────────────────
-echo "[setup] Downloading and installing the app libraries now..."
-echo "[setup] (This is the slow part. Watch the progress below.)"
-if ! "$PYEXE" -m pip install -r "$REQ" --disable-pip-version-check; then
-    _fail "Could not download/install the app libraries."
-fi
-
-# ── Write success marker (LAST, so a failed run safely retries) ───────────
-echo "installed $(date)" > "$MARKER"
-echo ""
-echo "[setup] Setup complete. Starting the app..."
-echo ""

scripts/package.sh

@@ -1,88 +0,0 @@
-#!/usr/bin/env bash
-# ===========================================================================
-#  package.sh - build a clean, ready-to-send client ZIP in ONE command.
-#
-#  Does everything for you, so nothing has to be excluded by hand:
-#    1. stages the bundled Windows Python into runtime\ (via prepare_bundle.sh),
-#    2. copies the project into a clean folder, EXCLUDING your secrets and
-#       dev-machine junk (.env / API key, .git, .vscode, .claude, caches, logs,
-#       tests, your personal sample_dossier files…),
-#    3. zips it to dist/UpworkProposalStrategist.zip,
-#    4. verifies the zip contains NO .env before declaring success.
-#
-#  Send dist/UpworkProposalStrategist.zip as-is.
-#
-#  Requirements: rsync, zip, curl, unzip (all ship with macOS).
-#  Usage:        bash scripts/package.sh
-# ===========================================================================
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
-
-NAME="UpworkProposalStrategist"          # client-facing folder + zip name
-DIST="${ROOT}/dist"
-STAGE="${DIST}/${NAME}"
-ZIP="${DIST}/${NAME}.zip"
-
-# --- 1. Make sure the bundled runtime is staged ----------------------------
-bash "${SCRIPT_DIR}/prepare_bundle.sh"
-
-# --- 2. Clean staging copy (exclude secrets + dev junk) --------------------
-echo
-echo "[package] Building a clean copy (excluding your .env / API key and dev files)..."
-rm -rf "${STAGE}"
-mkdir -p "${STAGE}"
-
-rsync -a \
-  --exclude '.git/' \
-  --exclude '.gitignore' \
-  --exclude '.env' \
-  --exclude '.env.tmp' \
-  --exclude '.env.local' \
-  --exclude '.env.production' \
-  --exclude '.vscode/' \
-  --exclude '.claude/' \
-  --exclude '.DS_Store' \
-  --exclude '__pycache__/' \
-  --exclude '*.pyc' \
-  --exclude '.pytest_cache/' \
-  --exclude '.mypy_cache/' \
-  --exclude '.ruff_cache/' \
-  --exclude 'logs/' \
-  --exclude 'dist/' \
-  --exclude 'tests/' \
-  --exclude 'sample_dossier/' \
-  --exclude '.python-embed.zip' \
-  "${ROOT}/" "${STAGE}/"
-
-# Re-add the two things we DO want that live under excluded patterns/paths:
-#   - .env.example: the template the app copies to create the user's .env.
-#   - the dossier TEMPLATE only (never the user's personal sample files).
-cp "${ROOT}/.env.example" "${STAGE}/.env.example"
-mkdir -p "${STAGE}/sample_dossier"
-cp "${ROOT}/sample_dossier/TEMPLATE_dossier.json" "${STAGE}/sample_dossier/TEMPLATE_dossier.json"
-
-# Safety net: never ship a real .env even if one ever slipped through.
-rm -f "${STAGE}/.env"
-
-# --- 3. Zip it -------------------------------------------------------------
-echo "[package] Zipping..."
-rm -f "${ZIP}"
-( cd "${DIST}" && zip -r -q -X "${NAME}.zip" "${NAME}" )
-rm -rf "${STAGE}"
-
-SIZE="$(du -h "${ZIP}" | cut -f1 | tr -d ' ')"
-
-# --- 4. Verify no secret leaked into the zip -------------------------------
-if unzip -l "${ZIP}" | grep -Eq '/\.env$'; then
-  echo "[package] !! WARNING: a .env file is inside the zip - DO NOT SEND IT." >&2
-  exit 1
-fi
-
-echo
-echo "[package] Done  ->  dist/${NAME}.zip  (${SIZE})"
-echo "[package] Verified: no .env (API key) inside. Safe to send."
-echo
-echo "Send dist/${NAME}.zip to your client. They unzip it and double-click"
-echo "\"Start Upwork Proposal Strategist\". Re-run this script after any change."

scripts/prepare_bundle.sh

@@ -1,53 +0,0 @@
-#!/usr/bin/env bash
-# ===========================================================================
-#  prepare_bundle.sh - (re)create the bundled Windows runtime in runtime/.
-#
-#  You normally DON'T need this: runtime/ (the embeddable Windows Python +
-#  get-pip.py) is committed to the repo, so a fresh checkout already has it. Use
-#  this only to rebuild a deleted/corrupted runtime, or to bump the pinned Python
-#  version (edit PYVER, delete runtime/, then re-run).
-#
-#  It downloads + unzips the embeddable Windows Python and get-pip.py into
-#  runtime/. The files are Windows binaries - we only stage them here, never
-#  execute them on macOS/Linux. The client never downloads an interpreter (the
-#  part antivirus/SmartScreen flags); their first run only pip-installs the
-#  libraries from PyPI (internet needed once).
-#
-#  Requirements: curl and unzip (both ship with macOS).
-#  Usage:        bash scripts/prepare_bundle.sh
-# ===========================================================================
-set -euo pipefail
-
-PYVER="3.11.9"   # keep in step with scripts/ensure_runtime.bat (python311._pth)
-PYZIP="python-${PYVER}-embed-amd64.zip"
-PYURL="https://www.python.org/ftp/python/${PYVER}/${PYZIP}"
-GETPIP_URL="https://bootstrap.pypa.io/get-pip.py"
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
-RT="${ROOT}/runtime"
-
-mkdir -p "${RT}"
-
-# --- 1. Embeddable Python -> runtime/ --------------------------------------
-if [ -f "${RT}/python.exe" ]; then
-  echo "[prepare] runtime/python.exe already present - skipping Python download."
-else
-  echo "[prepare] Downloading embeddable Python ${PYVER} (Windows)..."
-  TMPZIP="${RT}/.python-embed.zip"
-  curl -fSL "${PYURL}" -o "${TMPZIP}"
-  echo "[prepare] Extracting into runtime/ ..."
-  unzip -o -q "${TMPZIP}" -d "${RT}"
-  rm -f "${TMPZIP}"
-fi
-
-# --- 2. get-pip.py -> runtime/ ---------------------------------------------
-if [ -f "${RT}/get-pip.py" ]; then
-  echo "[prepare] runtime/get-pip.py already present - skipping."
-else
-  echo "[prepare] Downloading get-pip.py..."
-  curl -fSL "${GETPIP_URL}" -o "${RT}/get-pip.py"
-fi
-
-echo "[prepare] runtime/ staged ($(ls -1 "${RT}" | wc -l | tr -d ' ') files, incl. python.exe + get-pip.py)."
-echo "[prepare] To build a clean, ready-to-send zip, run:  bash scripts/package.sh"

scripts/run_mac.sh

@@ -1,64 +0,0 @@
-#!/usr/bin/env bash
-# ===========================================================================
-#  run_mac.sh — launch the Upwork Proposal Strategist on macOS.
-#
-#  Usage:
-#    ./scripts/run_mac.sh           normal mode (clean output)
-#    ./scripts/run_mac.sh debug     debug mode  (full Streamlit logs)
-#
-#  Called by the .command launchers in the project root.
-# ===========================================================================
-
-set -uo pipefail
-
-# Resolve the project root (this script lives in <root>/scripts/).
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-ROOT="$( cd "$SCRIPT_DIR/.." && pwd )"
-
-VENV="$ROOT/runtime_mac/venv"
-PYEXE="$VENV/bin/python"
-
-cd "$ROOT"
-
-# Sanity check: confirm the folder was fully extracted.
-if [ ! -f "desktop_app.py" ]; then
-    echo ""
-    echo "============================================================"
-    echo "  Core files are missing — this folder looks incomplete."
-    echo ""
-    echo "  Please make sure you extracted the FULL zip folder"
-    echo "  (right-click → 'Open With Archive Utility' on Mac),"
-    echo "  then launch the app from the extracted folder."
-    echo "============================================================"
-    echo ""
-    exit 1
-fi
-
-# Tell the app this is a packaged desktop run.
-export UPS_PACKAGED=1
-
-# Debug mode raises the log level.
-if [ "${1:-}" = "debug" ]; then
-    export UPS_DEBUG=1
-fi
-
-# First-run setup (no-op once installed).
-bash "$SCRIPT_DIR/ensure_runtime_mac.sh"
-if [ $? -ne 0 ]; then
-    echo ""
-    echo "Setup did not complete. Please try launching again."
-    exit 1
-fi
-
-echo ""
-echo " ============================================================"
-echo "   Upwork Proposal Strategist is running."
-echo "   Your web browser will open in a few seconds."
-echo ""
-echo "   >> KEEP THIS WINDOW OPEN while you use the app."
-echo "   >> To quit the app, close this window."
-echo " ============================================================"
-echo ""
-
-# Run the app. This call blocks until the window is closed.
-"$PYEXE" "desktop_app.py"